Add a logging appender API

instrumentation-api-appender/build.gradle.kts

@@ -0,0 +1,15 @@
+plugins {
+  id("otel.java-conventions")
+  id("otel.animalsniffer-conventions")
+  id("otel.jacoco-conventions")
+  id("otel.japicmp-conventions")
+  id("otel.publish-conventions")
+}
+
+group = "io.opentelemetry.instrumentation"
+
+dependencies {
+  api("io.opentelemetry:opentelemetry-api")
+
+  testImplementation("org.assertj:assertj-core")
+}

instrumentation-api-appender/src/main/java/io/opentelemetry/instrumentation/api/appender/GlobalLogEmitterProvider.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.appender;
+
+import javax.annotation.Nullable;
+
+public final class GlobalLogEmitterProvider {
+
+  private static final Object mutex = new Object();
+
+  private static volatile LogEmitterProvider globalLogEmitterProvider = null;
+
+  @Nullable private static Throwable setGlobalCaller;
+
+  /** Returns the registered global {@link LogEmitterProvider}. */
+  public static LogEmitterProvider get() {
+    LogEmitterProvider logEmitterProvider = globalLogEmitterProvider;
+    if (logEmitterProvider == null) {
+      synchronized (mutex) {
+        logEmitterProvider = globalLogEmitterProvider;
+        if (logEmitterProvider == null) {
+          set(NoopLogEmitterProvider.INSTANCE);
+          return NoopLogEmitterProvider.INSTANCE;
+        }
+      }
+    }
+    return logEmitterProvider;
+  }
+
+  /**
+   * Sets the {@link LogEmitterProvider} that should be the global instance. Future calls to {@link
+   * #get()} will return the provided {@link LogEmitterProvider} instance. This should be called
+   * once as early as possible in your application initialization logic, often in a {@code static}
+   * block in your main class. It should only be called once - an attempt to call it a second time
+   * will result in an error. If trying to set the global {@link LogEmitterProvider} multiple times
+   * in tests, use {@link GlobalLogEmitterProvider#resetForTest()} between them.
+   */
+  public static void set(LogEmitterProvider logEmitterProvider) {
+    synchronized (mutex) {
+      if (globalLogEmitterProvider != null) {
+        throw new IllegalStateException(
+            "GlobalLogEmitterProvider.set has already been called. GlobalLogEmitterProvider.set "
+                + "must be called only once before any calls to GlobalLogEmitterProvider.get. "
+                + "Previous invocation set to cause of this exception.",
+            setGlobalCaller);
+      }
+      globalLogEmitterProvider = logEmitterProvider;
+      setGlobalCaller = new Throwable();
+    }
+  }
+
+  /**
+   * Unsets the global {@link LogEmitterProvider}. This is only meant to be used from tests which
+   * need to reconfigure {@link LogEmitterProvider}.
+   */
+  public static void resetForTest() {
+    globalLogEmitterProvider = null;
+  }
+
+  private GlobalLogEmitterProvider() {}
+}

instrumentation-api-appender/src/main/java/io/opentelemetry/instrumentation/api/appender/LogBuilder.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.appender;
+
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.context.Context;
+import java.time.Instant;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Used to construct and emit logs from a {@link LogEmitter}.
+ *
+ * <p>Obtain a {@link LogBuilder} via {@link LogEmitter#logBuilder()}, add properties using the
+ * setters, and emit the log by calling {@link #emit()}.
+ */
+public interface LogBuilder {
+
+  /** Set the epoch timestamp using the timestamp and unit. */
+  LogBuilder setEpoch(long timestamp, TimeUnit unit);
+
+  /** Set the epoch timestamp using the instant. */
+  LogBuilder setEpoch(Instant instant);
+
+  /** Set the context. */
+  LogBuilder setContext(Context context);
+
+  /** Set the severity. */
+  LogBuilder setSeverity(Severity severity);
+
+  /** Set the severity text. */
+  LogBuilder setSeverityText(String severityText);
+
+  /** Set the name. */
+  LogBuilder setName(String name);
+
+  /** Set the body string. */
+  LogBuilder setBody(String body);
+
+  /** Set the attributes. */
+  LogBuilder setAttributes(Attributes attributes);
+
+  /** Emit the log. */
+  void emit();
+}

instrumentation-api-appender/src/main/java/io/opentelemetry/instrumentation/api/appender/LogEmitter.java

@@ -0,0 +1,21 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.appender;
+
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * A {@link LogEmitter} is the entry point into a log pipeline.
+ *
+ * <p>Obtain a log builder via {@link #logBuilder()}, add properties using the setters, and emit it
+ * via {@link LogBuilder#emit()}.
+ */
+@ThreadSafe
+public interface LogEmitter {
+
+  /** Return a new {@link LogBuilder} to emit a log. */
+  LogBuilder logBuilder();
+}

instrumentation-api-appender/src/main/java/io/opentelemetry/instrumentation/api/appender/LogEmitterBuilder.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.appender;
+
+/** Builder class for creating {@link LogEmitter} instances. */
+public interface LogEmitterBuilder {
+
+  /**
+   * Assign an OpenTelemetry schema URL to the resulting {@link LogEmitter}.
+   *
+   * @param schemaUrl the URL of the OpenTelemetry schema being used by this instrumentation library
+   * @return this
+   */
+  LogEmitterBuilder setSchemaUrl(String schemaUrl);
+
+  /**
+   * Assign a version to the instrumentation library that is using the resulting {@link LogEmitter}.
+   *
+   * @param instrumentationVersion the version of the instrumentation library
+   * @return this
+   */
+  LogEmitterBuilder setInstrumentationVersion(String instrumentationVersion);
+
+  /**
+   * Gets or creates a {@link LogEmitter} instance.
+   *
+   * @return a log emitter instance configured with the provided options
+   */
+  LogEmitter build();
+}

instrumentation-api-appender/src/main/java/io/opentelemetry/instrumentation/api/appender/LogEmitterProvider.java

@@ -0,0 +1,17 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.appender;
+
+public interface LogEmitterProvider {
+
+  /**
+   * Creates a {@link LogEmitterBuilder} instance.
+   *
+   * @param instrumentationName the name of the instrumentation library
+   * @return a log emitter builder instance
+   */
+  LogEmitterBuilder logEmitterBuilder(String instrumentationName);
+}

instrumentation-api-appender/src/main/java/io/opentelemetry/instrumentation/api/appender/NoopLogBuilder.java

@@ -0,0 +1,59 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.appender;
+
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.context.Context;
+import java.time.Instant;
+import java.util.concurrent.TimeUnit;
+
+final class NoopLogBuilder implements LogBuilder {
+
+  static final LogBuilder INSTANCE = new NoopLogBuilder();
+
+  @Override
+  public LogBuilder setEpoch(long timestamp, TimeUnit unit) {
+    return this;
+  }
+
+  @Override
+  public LogBuilder setEpoch(Instant instant) {
+    return this;
+  }
+
+  @Override
+  public LogBuilder setContext(Context context) {
+    return this;
+  }
+
+  @Override
+  public LogBuilder setSeverity(Severity severity) {
+    return this;
+  }
+
+  @Override
+  public LogBuilder setSeverityText(String severityText) {
+    return this;
+  }
+
+  @Override
+  public LogBuilder setName(String name) {
+    return this;
+  }
+
+  @Override
+  public LogBuilder setBody(String body) {
+    return this;
+  }
+
+  @Override
+  public LogBuilder setAttributes(Attributes attributes) {
+    return this;
+  }
+
+  @Override
+  public void emit() {}
+}

instrumentation-api-appender/src/main/java/io/opentelemetry/instrumentation/api/appender/NoopLogEmitter.java

@@ -0,0 +1,16 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.appender;
+
+final class NoopLogEmitter implements LogEmitter {
+
+  static final LogEmitter INSTANCE = new NoopLogEmitter();
+
+  @Override
+  public LogBuilder logBuilder() {
+    return NoopLogBuilder.INSTANCE;
+  }
+}

instrumentation-api-appender/src/main/java/io/opentelemetry/instrumentation/api/appender/NoopLogEmitterBuilder.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.appender;
+
+final class NoopLogEmitterBuilder implements LogEmitterBuilder {
+
+  static final LogEmitterBuilder INSTANCE = new NoopLogEmitterBuilder();
+
+  @Override
+  public LogEmitterBuilder setSchemaUrl(String schemaUrl) {
+    return this;
+  }
+
+  @Override
+  public LogEmitterBuilder setInstrumentationVersion(String instrumentationVersion) {
+    return this;
+  }
+
+  @Override
+  public LogEmitter build() {
+    return NoopLogEmitter.INSTANCE;
+  }
+}

instrumentation-api-appender/src/main/java/io/opentelemetry/instrumentation/api/appender/NoopLogEmitterProvider.java

@@ -0,0 +1,16 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.appender;
+
+final class NoopLogEmitterProvider implements LogEmitterProvider {
+
+  static final NoopLogEmitterProvider INSTANCE = new NoopLogEmitterProvider();
+
+  @Override
+  public LogEmitterBuilder logEmitterBuilder(String instrumentationName) {
+    return NoopLogEmitterBuilder.INSTANCE;
+  }
+}

instrumentation-api-appender/src/main/java/io/opentelemetry/instrumentation/api/appender/Severity.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.appender;
+
+public enum Severity {
+  UNDEFINED_SEVERITY_NUMBER(0),
+  TRACE(1),
+  TRACE2(2),
+  TRACE3(3),
+  TRACE4(4),
+  DEBUG(5),
+  DEBUG2(6),
+  DEBUG3(7),
+  DEBUG4(8),
+  INFO(9),
+  INFO2(10),
+  INFO3(11),
+  INFO4(12),
+  WARN(13),
+  WARN2(14),
+  WARN3(15),
+  WARN4(16),
+  ERROR(17),
+  ERROR2(18),
+  ERROR3(19),
+  ERROR4(20),
+  FATAL(21),
+  FATAL2(22),
+  FATAL3(23),
+  FATAL4(24);
+
+  private final int severityNumber;
+
+  Severity(int severityNumber) {
+    this.severityNumber = severityNumber;
+  }
+
+  public int getSeverityNumber() {
+    return severityNumber;
+  }
+}