Stabilize log record event name (#7277)

jack-berg · web-flow · commit 9e1e9c6e9fb6 · 2025-04-17T12:30:43.000-05:00
diff --git a/api/all/src/main/java/io/opentelemetry/api/logs/LogRecordBuilder.java b/api/all/src/main/java/io/opentelemetry/api/logs/LogRecordBuilder.java
@@ -198,6 +198,16 @@ default LogRecordBuilder setAttribute(String key, int value) {
     return setAttribute(key, (long) value);
   }
 
+  /**
+   * Sets the event name, which identifies the class / type of the Event.
+   *
+   * <p>This name should uniquely identify the event structure (both attributes and body). A log
+   * record with a non-empty event name is an Event.
+   */
+  default LogRecordBuilder setEventName(String eventName) {
+    return this;
+  }
+
   /** Emit the log record. */
   void emit();
 }
diff --git a/api/incubator/src/main/java/io/opentelemetry/api/incubator/logs/ExtendedLogRecordBuilder.java b/api/incubator/src/main/java/io/opentelemetry/api/incubator/logs/ExtendedLogRecordBuilder.java
@@ -61,6 +61,15 @@ default ExtendedLogRecordBuilder setBody(Value<?> body) {
     return this;
   }
 
+  /**
+   * Sets the event name, which identifies the class / type of the Event.
+   *
+   * <p>This name should uniquely identify the event structure (both attributes and body). A log
+   * record with a non-empty event name is an Event.
+   */
+  @Override
+  ExtendedLogRecordBuilder setEventName(String eventName);
+
   /**
    * {@inheritDoc}
    *
@@ -124,14 +133,6 @@ default ExtendedLogRecordBuilder setAllAttributes(ExtendedAttributes attributes)
    */
   <T> ExtendedLogRecordBuilder setAttribute(ExtendedAttributeKey<T> key, T value);
 
-  /**
-   * Sets the event name, which identifies the class / type of the Event.
-   *
-   * <p>This name should uniquely identify the event structure (both attributes and body). A log
-   * record with a non-empty event name is an Event.
-   */
-  ExtendedLogRecordBuilder setEventName(String eventName);
-
   /** Set standard {@code exception.*} attributes based on the {@code throwable}. */
   ExtendedLogRecordBuilder setException(Throwable throwable);
 }
diff --git a/api/testing-internal/src/main/java/io/opentelemetry/api/testing/internal/AbstractDefaultLoggerTest.java b/api/testing-internal/src/main/java/io/opentelemetry/api/testing/internal/AbstractDefaultLoggerTest.java
@@ -51,8 +51,7 @@ void buildAndEmit() {
             () ->
                 getLogger()
                     .logRecordBuilder()
-                    // TODO (trask) once event name stabilizes
-                    //  .setEventName("event name")
+                    .setEventName("event name")
                     .setTimestamp(100, TimeUnit.SECONDS)
                     .setTimestamp(Instant.now())
                     .setObservedTimestamp(100, TimeUnit.SECONDS)
diff --git a/docs/apidiffs/current_vs_latest/opentelemetry-api.txt b/docs/apidiffs/current_vs_latest/opentelemetry-api.txt
@@ -1,2 +1,4 @@
 Comparing source compatibility of opentelemetry-api-1.50.0-SNAPSHOT.jar against opentelemetry-api-1.49.0.jar
-No changes.
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.api.logs.LogRecordBuilder  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.api.logs.LogRecordBuilder setEventName(java.lang.String)
diff --git a/docs/apidiffs/current_vs_latest/opentelemetry-sdk-logs.txt b/docs/apidiffs/current_vs_latest/opentelemetry-sdk-logs.txt
@@ -1,2 +1,9 @@
 Comparing source compatibility of opentelemetry-sdk-logs-1.50.0-SNAPSHOT.jar against opentelemetry-sdk-logs-1.49.0.jar
-No changes.
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.logs.data.LogRecordData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) java.lang.String getEventName()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.logs.ReadWriteLogRecord  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) java.lang.String getEventName()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
diff --git a/docs/apidiffs/current_vs_latest/opentelemetry-sdk-testing.txt b/docs/apidiffs/current_vs_latest/opentelemetry-sdk-testing.txt
@@ -1,4 +1,14 @@
 Comparing source compatibility of opentelemetry-sdk-testing-1.50.0-SNAPSHOT.jar against opentelemetry-sdk-testing-1.49.0.jar
+***  MODIFIED CLASS: PUBLIC FINAL io.opentelemetry.sdk.testing.assertj.LogRecordDataAssert  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.sdk.testing.assertj.LogRecordDataAssert hasEventName(java.lang.String)
+**** MODIFIED CLASS: PUBLIC ABSTRACT io.opentelemetry.sdk.testing.logs.TestLogRecordData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++* NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String getEventName()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+**** MODIFIED CLASS: PUBLIC ABSTRACT STATIC io.opentelemetry.sdk.testing.logs.TestLogRecordData$Builder  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++* NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.testing.logs.TestLogRecordData$Builder setEventName(java.lang.String)
 +++  NEW CLASS: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.testing.metrics.TestMetricData  (not serializable)
 	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
 	+++  NEW SUPERCLASS: java.lang.Object
diff --git a/exporters/otlp/common/src/main/java/io/opentelemetry/exporter/internal/otlp/logs/LogMarshaler.java b/exporters/otlp/common/src/main/java/io/opentelemetry/exporter/internal/otlp/logs/LogMarshaler.java
@@ -20,7 +20,6 @@
 import io.opentelemetry.proto.logs.v1.internal.LogRecord;
 import io.opentelemetry.proto.logs.v1.internal.SeverityNumber;
 import io.opentelemetry.sdk.logs.data.LogRecordData;
-import io.opentelemetry.sdk.logs.data.internal.ExtendedLogRecordData;
 import java.io.IOException;
 import javax.annotation.Nullable;
 
@@ -40,7 +39,6 @@ final class LogMarshaler extends MarshalerWithSize {
 
   private static final String INVALID_TRACE_ID = TraceId.getInvalid();
   private static final String INVALID_SPAN_ID = SpanId.getInvalid();
-  private static final byte[] EMPTY_BYTES = new byte[0];
 
   private final long timeUnixNano;
   private final long observedTimeUnixNano;
@@ -82,9 +80,7 @@ static LogMarshaler create(LogRecordData logRecordData) {
         spanContext.getTraceFlags(),
         spanContext.getTraceId().equals(INVALID_TRACE_ID) ? null : spanContext.getTraceId(),
         spanContext.getSpanId().equals(INVALID_SPAN_ID) ? null : spanContext.getSpanId(),
-        logRecordData instanceof ExtendedLogRecordData
-            ? MarshalerUtil.toBytes(((ExtendedLogRecordData) logRecordData).getEventName())
-            : EMPTY_BYTES);
+        MarshalerUtil.toBytes(logRecordData.getEventName()));
   }
 
   private LogMarshaler(
diff --git a/exporters/otlp/common/src/main/java/io/opentelemetry/exporter/internal/otlp/logs/LogStatelessMarshaler.java b/exporters/otlp/common/src/main/java/io/opentelemetry/exporter/internal/otlp/logs/LogStatelessMarshaler.java
@@ -20,7 +20,6 @@
 import io.opentelemetry.exporter.internal.otlp.IncubatingUtil;
 import io.opentelemetry.proto.logs.v1.internal.LogRecord;
 import io.opentelemetry.sdk.logs.data.LogRecordData;
-import io.opentelemetry.sdk.logs.data.internal.ExtendedLogRecordData;
 import java.io.IOException;
 
 /** See {@link LogMarshaler}. */
@@ -79,10 +78,7 @@ public void writeTo(Serializer output, LogRecordData log, MarshalerContext conte
     if (!spanContext.getSpanId().equals(INVALID_SPAN_ID)) {
       output.serializeSpanId(LogRecord.SPAN_ID, spanContext.getSpanId(), context);
     }
-    if (log instanceof ExtendedLogRecordData) {
-      output.serializeStringWithContext(
-          LogRecord.EVENT_NAME, ((ExtendedLogRecordData) log).getEventName(), context);
-    }
+    output.serializeStringWithContext(LogRecord.EVENT_NAME, log.getEventName(), context);
   }
 
   @Override
@@ -130,11 +126,9 @@ public int getBinarySerializedSize(LogRecordData log, MarshalerContext context)
       size += MarshalerUtil.sizeSpanId(LogRecord.SPAN_ID, spanContext.getSpanId());
     }
 
-    if (log instanceof ExtendedLogRecordData) {
-      size +=
-          StatelessMarshalerUtil.sizeStringWithContext(
-              LogRecord.EVENT_NAME, ((ExtendedLogRecordData) log).getEventName(), context);
-    }
+    size +=
+        StatelessMarshalerUtil.sizeStringWithContext(
+            LogRecord.EVENT_NAME, log.getEventName(), context);
 
     return size;
   }
diff --git a/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/ExtendedSdkLogRecordBuilder.java b/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/ExtendedSdkLogRecordBuilder.java
@@ -23,7 +23,6 @@
 final class ExtendedSdkLogRecordBuilder extends SdkLogRecordBuilder
     implements ExtendedLogRecordBuilder {
 
-  @Nullable private String eventName;
   @Nullable private ExtendedAttributesMap extendedAttributes;
 
   ExtendedSdkLogRecordBuilder(
@@ -33,7 +32,7 @@ final class ExtendedSdkLogRecordBuilder extends SdkLogRecordBuilder
 
   @Override
   public ExtendedSdkLogRecordBuilder setEventName(String eventName) {
-    this.eventName = eventName;
+    super.setEventName(eventName);
     return this;
   }
 
diff --git a/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/ExtendedSdkLogRecordData.java b/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/ExtendedSdkLogRecordData.java
@@ -44,15 +44,19 @@ static ExtendedSdkLogRecordData create(
         severity,
         severityText,
         totalAttributeCount,
-        eventName,
         attributes,
-        body);
+        body,
+        eventName);
   }
 
   @Override
   @Nullable
   public abstract Value<?> getBodyValue();
 
+  @Override
+  @Nullable
+  public abstract String getEventName();
+
   @Override
   @SuppressWarnings("deprecation") // Implementation of deprecated method
   public io.opentelemetry.sdk.logs.data.Body getBody() {
diff --git a/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/ExtendedSdkReadWriteLogRecord.java b/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/ExtendedSdkReadWriteLogRecord.java
@@ -25,7 +25,6 @@
 class ExtendedSdkReadWriteLogRecord extends SdkReadWriteLogRecord
     implements ExtendedReadWriteLogRecord {
 
-  @Nullable private final String eventName;
   private final Object lock = new Object();
 
   @GuardedBy("lock")
@@ -55,8 +54,8 @@ private ExtendedSdkReadWriteLogRecord(
         severity,
         severityText,
         body,
-        null);
-    this.eventName = eventName;
+        null,
+        eventName);
     this.extendedAttributes = extendedAttributes;
   }
 
diff --git a/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/ReadWriteLogRecord.java b/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/ReadWriteLogRecord.java
@@ -52,7 +52,11 @@ default ReadWriteLogRecord setAllAttributes(Attributes attributes) {
   /** Return an immutable {@link LogRecordData} instance representing this log record. */
   LogRecordData toLogRecordData();
 
-  // TODO (trask) once event name stabilizes, add getEventName()
+  /** Returns the log record event name, or {@code null} if none is set. */
+  @Nullable
+  default String getEventName() {
+    return null;
+  }
 
   /**
    * Returns the value of a given attribute if it exists. This is the equivalent of calling {@code
diff --git a/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/SdkLogRecordBuilder.java b/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/SdkLogRecordBuilder.java
@@ -30,6 +30,7 @@ class SdkLogRecordBuilder implements LogRecordBuilder {
   protected Severity severity = Severity.UNDEFINED_SEVERITY_NUMBER;
   @Nullable protected String severityText;
   @Nullable protected Value<?> body;
+  @Nullable protected String eventName;
   @Nullable private AttributesMap attributes;
 
   SdkLogRecordBuilder(
@@ -39,6 +40,12 @@ class SdkLogRecordBuilder implements LogRecordBuilder {
     this.instrumentationScopeInfo = instrumentationScopeInfo;
   }
 
+  @Override
+  public SdkLogRecordBuilder setEventName(String eventName) {
+    this.eventName = eventName;
+    return this;
+  }
+
   @Override
   public SdkLogRecordBuilder setTimestamp(long timestamp, TimeUnit unit) {
     this.timestampEpochNanos = unit.toNanos(timestamp);
@@ -132,6 +139,7 @@ public void emit() {
                 severity,
                 severityText,
                 body,
-                attributes));
+                attributes,
+                eventName));
   }
 }
diff --git a/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/SdkLogRecordData.java b/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/SdkLogRecordData.java
@@ -33,7 +33,8 @@ static SdkLogRecordData create(
       @Nullable String severityText,
       @Nullable Value<?> body,
       Attributes attributes,
-      int totalAttributeCount) {
+      int totalAttributeCount,
+      @Nullable String eventName) {
     return new AutoValue_SdkLogRecordData(
         resource,
         instrumentationScopeInfo,
@@ -44,13 +45,18 @@ static SdkLogRecordData create(
         severityText,
         attributes,
         totalAttributeCount,
-        body);
+        body,
+        eventName);
   }
 
   @Override
   @Nullable
   public abstract Value<?> getBodyValue();
 
+  @Override
+  @Nullable
+  public abstract String getEventName();
+
   @Override
   @SuppressWarnings("deprecation") // Implementation of deprecated method
   public io.opentelemetry.sdk.logs.data.Body getBody() {
diff --git a/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/SdkReadWriteLogRecord.java b/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/SdkReadWriteLogRecord.java
@@ -30,6 +30,7 @@ class SdkReadWriteLogRecord implements ReadWriteLogRecord {
   protected final Severity severity;
   @Nullable protected final String severityText;
   @Nullable protected final Value<?> body;
+  @Nullable protected String eventName;
   private final Object lock = new Object();
 
   @GuardedBy("lock")
@@ -46,7 +47,8 @@ protected SdkReadWriteLogRecord(
       Severity severity,
       @Nullable String severityText,
       @Nullable Value<?> body,
-      @Nullable AttributesMap attributes) {
+      @Nullable AttributesMap attributes,
+      @Nullable String eventName) {
     this.logLimits = logLimits;
     this.resource = resource;
     this.instrumentationScopeInfo = instrumentationScopeInfo;
@@ -56,6 +58,7 @@ protected SdkReadWriteLogRecord(
     this.severity = severity;
     this.severityText = severityText;
     this.body = body;
+    this.eventName = eventName;
     this.attributes = attributes;
   }
 
@@ -70,7 +73,8 @@ static SdkReadWriteLogRecord create(
       Severity severity,
       @Nullable String severityText,
       @Nullable Value<?> body,
-      @Nullable AttributesMap attributes) {
+      @Nullable AttributesMap attributes,
+      @Nullable String eventName) {
     return new SdkReadWriteLogRecord(
         logLimits,
         resource,
@@ -81,7 +85,8 @@ static SdkReadWriteLogRecord create(
         severity,
         severityText,
         body,
-        attributes);
+        attributes,
+        eventName);
   }
 
   @Override
@@ -122,7 +127,8 @@ public LogRecordData toLogRecordData() {
           severityText,
           body,
           getImmutableAttributes(),
-          attributes == null ? 0 : attributes.getTotalAddedValues());
+          attributes == null ? 0 : attributes.getTotalAddedValues(),
+          eventName);
     }
   }
 
@@ -168,6 +174,12 @@ public Attributes getAttributes() {
     return getImmutableAttributes();
   }
 
+  @Override
+  @Nullable
+  public String getEventName() {
+    return eventName;
+  }
+
   @Nullable
   @Override
   public <T> T getAttribute(AttributeKey<T> key) {
diff --git a/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/data/LogRecordData.java b/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/data/LogRecordData.java
@@ -82,4 +82,10 @@ default Value<?> getBodyValue() {
    * LogLimits#getMaxNumberOfAttributes()}.
    */
   int getTotalAttributeCount();
+
+  /** Returns the event name, or {@code null} if none is set. */
+  @Nullable
+  default String getEventName() {
+    return null;
+  }
 }
diff --git a/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/data/internal/ExtendedLogRecordData.java b/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/data/internal/ExtendedLogRecordData.java
@@ -8,7 +8,6 @@
 import io.opentelemetry.api.common.Attributes;
 import io.opentelemetry.api.incubator.common.ExtendedAttributes;
 import io.opentelemetry.sdk.logs.data.LogRecordData;
-import javax.annotation.Nullable;
 
 /**
  * This class is internal and experimental. Its APIs are unstable and can change at any time. Its
@@ -17,9 +16,6 @@
  */
 public interface ExtendedLogRecordData extends LogRecordData {
 
-  @Nullable
-  String getEventName();
-
   /** Returns the attributes for this log, or {@link ExtendedAttributes#empty()} if unset. */
   ExtendedAttributes getExtendedAttributes();
 
diff --git a/sdk/logs/src/test/java/io/opentelemetry/sdk/logs/ReadWriteLogRecordTest.java b/sdk/logs/src/test/java/io/opentelemetry/sdk/logs/ReadWriteLogRecordTest.java
@@ -68,6 +68,7 @@ SdkReadWriteLogRecord buildLogRecord() {
         Severity.DEBUG,
         "buggin",
         body,
-        initialAttributes);
+        initialAttributes,
+        "my.event.name");
   }
 }
diff --git a/sdk/logs/src/test/java/io/opentelemetry/sdk/logs/SdkLogRecordBuilderTest.java b/sdk/logs/src/test/java/io/opentelemetry/sdk/logs/SdkLogRecordBuilderTest.java
diff --git a/sdk/logs/src/test/java/io/opentelemetry/sdk/logs/SdkLoggerProviderTest.java b/sdk/logs/src/test/java/io/opentelemetry/sdk/logs/SdkLoggerProviderTest.java
diff --git a/sdk/testing/src/main/java/io/opentelemetry/sdk/testing/assertj/LogRecordDataAssert.java b/sdk/testing/src/main/java/io/opentelemetry/sdk/testing/assertj/LogRecordDataAssert.java
diff --git a/sdk/testing/src/main/java/io/opentelemetry/sdk/testing/logs/TestLogRecordData.java b/sdk/testing/src/main/java/io/opentelemetry/sdk/testing/logs/TestLogRecordData.java
diff --git a/sdk/testing/src/main/java/io/opentelemetry/sdk/testing/logs/internal/TestExtendedLogRecordData.java b/sdk/testing/src/main/java/io/opentelemetry/sdk/testing/logs/internal/TestExtendedLogRecordData.java
diff --git a/sdk/testing/src/test/java/io/opentelemetry/sdk/testing/assertj/LogAssertionsTest.java b/sdk/testing/src/test/java/io/opentelemetry/sdk/testing/assertj/LogAssertionsTest.java
