Promote log API / SDK to stable (#5341)

README.md

@@ -224,8 +224,7 @@ dependency as follows, replacing `{{artifact-id}}` with the value from the "Arti
 | Component                         | Description                                                                                                                    | Artifact ID                | Version                                                     | Javadoc                                                                                                                                                         |
 |-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------|----------------------------|-------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | [API](./api/all)                  | OpenTelemetry API, including metrics, traces, baggage, context                                                                 | `opentelemetry-api`        | <!--VERSION_STABLE-->1.26.0<!--/VERSION_STABLE-->           | [![Javadocs](https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-api.svg)](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api)               |
-| [Events API](./api/logs)          | OpenTelemetry Event API for emitting events.                                                                                   | `opentelemetry-api-events` | <!--VERSION_UNSTABLE-->1.26.0-alpha<!--/VERSION_UNSTABLE--> | [![Javadocs](https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-api-events.svg)](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api-events) |
-| [Logs API](./api/logs)            | OpenTelemetry Log API for bridging log frameworks (NOT a replacement for application logging frameworks like SLF4J, JUL, etc.) | `opentelemetry-api-logs`   | <!--VERSION_UNSTABLE-->1.26.0-alpha<!--/VERSION_UNSTABLE--> | [![Javadocs](https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-api-logs.svg)](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api-logs)     |
+| [Events API](./api/events)        | OpenTelemetry Event API for emitting events.                                                                                   | `opentelemetry-api-events` | <!--VERSION_UNSTABLE-->1.26.0-alpha<!--/VERSION_UNSTABLE--> | [![Javadocs](https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-api-events.svg)](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api-events) |
 | [Context API](./context)          | OpenTelemetry context API                                                                                                      | `opentelemetry-context`    | <!--VERSION_STABLE-->1.26.0<!--/VERSION_STABLE-->           | [![Javadocs](https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-context.svg)](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-context)       |
 | [Semantic Conventions](./semconv) | Generated code for OpenTelemetry semantic conventions                                                                          | `opentelemetry-semconv`    | <!--VERSION_UNSTABLE-->1.26.0-alpha<!--/VERSION_UNSTABLE--> | [![Javadocs](https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-semconv.svg)](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-semconv)       |
 

api/all/src/main/java/io/opentelemetry/api/GlobalOpenTelemetry.java

@@ -7,6 +7,7 @@
 
 import io.opentelemetry.api.internal.ConfigUtil;
 import io.opentelemetry.api.internal.GuardedBy;
+import io.opentelemetry.api.logs.LoggerProvider;
 import io.opentelemetry.api.metrics.Meter;
 import io.opentelemetry.api.metrics.MeterBuilder;
 import io.opentelemetry.api.metrics.MeterProvider;
@@ -281,6 +282,11 @@ public MeterProvider getMeterProvider() {
       return delegate.getMeterProvider();
     }
 
+    @Override
+    public LoggerProvider getLogsBridge() {
+      return delegate.getLogsBridge();
+    }
+
     @Override
     public ContextPropagators getPropagators() {
       return delegate.getPropagators();

api/all/src/main/java/io/opentelemetry/api/OpenTelemetry.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.api;
 
+import io.opentelemetry.api.logs.LoggerProvider;
 import io.opentelemetry.api.metrics.Meter;
 import io.opentelemetry.api.metrics.MeterBuilder;
 import io.opentelemetry.api.metrics.MeterProvider;
@@ -113,6 +114,19 @@ default MeterBuilder meterBuilder(String instrumentationScopeName) {
     return getMeterProvider().meterBuilder(instrumentationScopeName);
   }
 
+  /**
+   * Returns the {@link LoggerProvider} for bridging logs into OpenTelemetry.
+   *
+   * <p>The OpenTelemetry logs bridge API exists to enable bridging logs from other log frameworks
+   * (e.g. SLF4J, Log4j, JUL, Logback, etc) into OpenTelemetry and is <b>NOT</b> a replacement log
+   * API.
+   *
+   * @since 1.27.0
+   */
+  default LoggerProvider getLogsBridge() {
+    return LoggerProvider.noop();
+  }
+
   /** Returns the {@link ContextPropagators} for this {@link OpenTelemetry}. */
   ContextPropagators getPropagators();
 }

api/logs/src/main/java/io/opentelemetry/api/logs/LogRecordBuilder.java → api/all/src/main/java/io/opentelemetry/api/logs/LogRecordBuilder.java

@@ -16,6 +16,8 @@
  *
  * <p>Obtain a {@link Logger#logRecordBuilder()}, add properties using the setters, and emit the log
  * record by calling {@link #emit()}.
+ *
+ * @since 1.27.0
  */
 public interface LogRecordBuilder {
 

api/logs/src/main/java/io/opentelemetry/api/logs/Logger.java → api/all/src/main/java/io/opentelemetry/api/logs/Logger.java

@@ -12,6 +12,12 @@
  *
  * <p>Obtain a {@link #logRecordBuilder()}, add properties using the setters, and emit it via {@link
  * LogRecordBuilder#emit()}.
+ *
+ * <p>The OpenTelemetry logs bridge API exists to enable bridging logs from other log frameworks
+ * (e.g. SLF4J, Log4j, JUL, Logback, etc) into OpenTelemetry and is <b>NOT</b> a replacement log
+ * API.
+ *
+ * @since 1.27.0
  */
 @ThreadSafe
 public interface Logger {

api/logs/src/main/java/io/opentelemetry/api/logs/LoggerBuilder.java → api/all/src/main/java/io/opentelemetry/api/logs/LoggerBuilder.java

@@ -11,6 +11,8 @@
  * <p>{@link Logger}s are identified by their scope name, version, and schema URL. These identifying
  * fields, along with attributes, combine to form the instrumentation scope, which is attached to
  * all log records produced by the {@link Logger}.
+ *
+ * @since 1.27.0
  */
 public interface LoggerBuilder {
 

api/logs/src/main/java/io/opentelemetry/api/logs/LoggerProvider.java → api/all/src/main/java/io/opentelemetry/api/logs/LoggerProvider.java

@@ -11,10 +11,11 @@
  * A registry for creating scoped {@link Logger}s. The name <i>Provider</i> is for consistency with
  * other languages and it is <b>NOT</b> loaded using reflection.
  *
- * <p>The OpenTelemetry logging API exists to enable the creation of log appenders, which bridge
- * logs from other log frameworks (e.g. SLF4J, Log4j, JUL, Logback, etc) into OpenTelemetry via
- * {@link Logger#logRecordBuilder()}. It is <b>NOT</b> a replacement log framework.
+ * <p>The OpenTelemetry logs bridge API exists to enable bridging logs from other log frameworks
+ * (e.g. SLF4J, Log4j, JUL, Logback, etc) into OpenTelemetry and is <b>NOT</b> a replacement log
+ * API.
  *
+ * @since 1.27.0
  * @see Logger
  */
 @ThreadSafe

api/logs/src/main/java/io/opentelemetry/api/logs/Severity.java → api/all/src/main/java/io/opentelemetry/api/logs/Severity.java

@@ -5,6 +5,11 @@
 
 package io.opentelemetry.api.logs;
 
+/**
+ * Log record severity options.
+ *
+ * @since 1.27.0
+ */
 public enum Severity {
   UNDEFINED_SEVERITY_NUMBER(0),
   TRACE(1),

api/all/src/main/java/io/opentelemetry/api/logs/package-info.java

@@ -0,0 +1,17 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * API for writing log appenders.
+ *
+ * <p>The OpenTelemetry logging API exists to enable the creation of log appenders, which bridge
+ * logs from other log frameworks (e.g. SLF4J, Log4j, JUL, Logback, etc) into OpenTelemetry via
+ * {@link io.opentelemetry.api.logs.Logger#logRecordBuilder()}. It is <b>NOT</b> a replacement log
+ * framework.
+ */
+@ParametersAreNonnullByDefault
+package io.opentelemetry.api.logs;
+
+import javax.annotation.ParametersAreNonnullByDefault;

api/all/src/test/java/io/opentelemetry/api/OpenTelemetryTest.java

@@ -9,6 +9,7 @@
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.mockito.Mockito.mock;
 
+import io.opentelemetry.api.logs.LoggerProvider;
 import io.opentelemetry.api.metrics.MeterProvider;
 import io.opentelemetry.api.trace.TracerProvider;
 import io.opentelemetry.context.propagation.ContextPropagators;
@@ -33,6 +34,7 @@ void testDefault() {
     assertThat(OpenTelemetry.noop().getTracerProvider()).isSameAs(TracerProvider.noop());
     assertThat(OpenTelemetry.noop().getPropagators()).isSameAs(ContextPropagators.noop());
     assertThat(OpenTelemetry.noop().getMeterProvider()).isSameAs(MeterProvider.noop());
+    assertThat(OpenTelemetry.noop().getLogsBridge()).isSameAs(LoggerProvider.noop());
   }
 
   @Test
@@ -42,6 +44,7 @@ void propagating() {
 
     assertThat(openTelemetry.getTracerProvider()).isSameAs(TracerProvider.noop());
     assertThat(openTelemetry.getMeterProvider()).isSameAs(MeterProvider.noop());
+    assertThat(openTelemetry.getLogsBridge()).isSameAs(LoggerProvider.noop());
     assertThat(openTelemetry.getPropagators()).isSameAs(contextPropagators);
   }
 

docs/apidiffs/current_vs_latest/opentelemetry-api.txt

@@ -1,2 +1,68 @@
 Comparing source compatibility of  against 
-No changes.
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.Logger  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LogRecordBuilder logRecordBuilder()
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LoggerBuilder  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.Logger build()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LoggerBuilder setInstrumentationVersion(java.lang.String)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LoggerBuilder setSchemaUrl(java.lang.String)
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LoggerProvider  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.api.logs.Logger get(java.lang.String)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LoggerBuilder loggerBuilder(java.lang.String)
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.api.logs.LoggerProvider noop()
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LogRecordBuilder  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void emit()
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.api.logs.LogRecordBuilder setAllAttributes(io.opentelemetry.api.common.Attributes)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LogRecordBuilder setAttribute(io.opentelemetry.api.common.AttributeKey, java.lang.Object)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LogRecordBuilder setBody(java.lang.String)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LogRecordBuilder setContext(io.opentelemetry.context.Context)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LogRecordBuilder setObservedTimestamp(long, java.util.concurrent.TimeUnit)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LogRecordBuilder setObservedTimestamp(java.time.Instant)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LogRecordBuilder setSeverity(io.opentelemetry.api.logs.Severity)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LogRecordBuilder setSeverityText(java.lang.String)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LogRecordBuilder setTimestamp(long, java.util.concurrent.TimeUnit)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.logs.LogRecordBuilder setTimestamp(java.time.Instant)
++++  NEW ENUM: PUBLIC(+) FINAL(+) io.opentelemetry.api.logs.Severity  (compatible)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW INTERFACE: java.lang.constant.Constable
+	+++  NEW INTERFACE: java.lang.Comparable
+	+++  NEW INTERFACE: java.io.Serializable
+	+++  NEW SUPERCLASS: java.lang.Enum
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity WARN2
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity WARN3
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity WARN4
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity INFO
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity TRACE2
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity DEBUG4
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity DEBUG3
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity TRACE4
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity TRACE3
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity ERROR
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity FATAL
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity TRACE
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity FATAL2
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity FATAL3
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity ERROR2
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity ERROR3
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity ERROR4
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity DEBUG2
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity INFO3
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity DEBUG
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity INFO2
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity WARN
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity INFO4
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity UNDEFINED_SEVERITY_NUMBER
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.logs.Severity FATAL4
+	+++  NEW METHOD: PUBLIC(+) int getSeverityNumber()
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.api.logs.Severity valueOf(java.lang.String)
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.api.logs.Severity[] values()
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.api.OpenTelemetry  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.api.logs.LoggerProvider getLogsBridge()