Add opt-in support for emitting exceptions as log signals (#16259)

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: trask

.github/instructions/java-tests.instructions.md

@@ -66,3 +66,11 @@ reserved). Use `v` only for a nested inner-lambda parameter.
 This guidance applies only to attribute-assertion `satisfies(...)`; for
 `span.satisfies(...)`, `point.satisfies(...)`, etc. use a descriptive name
 (`spanData`, `pointData`, `result`).
+
+It also applies only to lambdas written **directly inline** as the
+`satisfies(AttributeKey, lambda)` argument, where the attribute key already
+documents what is being asserted. Do **not** flag lambdas passed to a custom
+helper method (e.g. `assertExceptionLog(typeAssertion, messageAssertion)`),
+even though the parameter is the same `AbstractStringAssert` type. There a
+descriptive name documents which attribute each lambda asserts, and renaming
+multiple parameters to `val` loses that context.

declarative-config-bridge/src/main/java/io/opentelemetry/instrumentation/config/bridge/ConfigPropertiesBackedDeclarativeConfigProperties.java

@@ -51,6 +51,8 @@ public final class ConfigPropertiesBackedDeclarativeConfigProperties
         "general.sanitization.url.sensitive_query_parameters/development",
         "otel.instrumentation.sanitization.url.experimental.sensitive-query-parameters");
     SPECIAL_MAPPINGS.put("general.semconv_stability.opt_in", "otel.semconv-stability.opt-in");
+    SPECIAL_MAPPINGS.put(
+        "general.semconv_exception.signal.preview", "otel.semconv.exception.signal.preview");
     // moving common http, database, messaging, and gen_ai configs under common
     SPECIAL_MAPPINGS.put(
         "java.common.http.known_methods", "otel.instrumentation.http.known-methods");

instrumentation-api-incubator/build.gradle.kts

@@ -102,7 +102,21 @@ tasks {
     inputs.dir(jflexOutputDir)
   }
 
+  val testExceptionSignalLogs by registering(Test::class) {
+    testClassesDirs = sourceSets.test.get().output.classesDirs
+    classpath = sourceSets.test.get().runtimeClasspath
+    jvmArgs("-Dotel.semconv.exception.signal.preview=logs")
+    inputs.dir(jflexOutputDir)
+  }
+
+  val testExceptionSignalLogsDup by registering(Test::class) {
+    testClassesDirs = sourceSets.test.get().output.classesDirs
+    classpath = sourceSets.test.get().runtimeClasspath
+    jvmArgs("-Dotel.semconv.exception.signal.preview=logs/dup")
+    inputs.dir(jflexOutputDir)
+  }
+
   check {
-    dependsOn(testStableSemconv, testBothSemconv)
+    dependsOn(testStableSemconv, testBothSemconv, testExceptionSignalLogs, testExceptionSignalLogsDup)
   }
 }

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/builder/internal/DefaultHttpClientInstrumenterBuilder.java

@@ -9,6 +9,7 @@
 
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.logs.Severity;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.context.propagation.TextMapSetter;
 import io.opentelemetry.instrumentation.api.incubator.config.internal.CommonConfig;
@@ -225,7 +226,8 @@ public Instrumenter<REQUEST, RESPONSE> build() {
             .addAttributesExtractor(httpAttributesExtractorBuilder.build())
             .addAttributesExtractors(additionalExtractors)
             .addOperationMetrics(HttpClientMetrics.get())
-            .setSchemaUrl(SchemaUrls.V1_37_0);
+            .setSchemaUrl(SchemaUrls.V1_41_0);
+    setHttpClientExceptionEventExtractor(builder);
     if (emitExperimentalHttpClientTelemetry) {
       builder
           .addAttributesExtractor(HttpExperimentalAttributesExtractor.create(attributesGetter))
@@ -245,7 +247,17 @@ InstrumenterBuilder<BUILDERREQUEST, BUILDERRESPONSE> instrumenterBuilder(
           SpanNameExtractor<? super BUILDERREQUEST> spanNameExtractor) {
     return Instrumenter.<BUILDERREQUEST, BUILDERRESPONSE>builder(
             openTelemetry, instrumentationName, spanNameExtractor)
-        .setSchemaUrl(SchemaUrls.V1_37_0);
+        .setSchemaUrl(SchemaUrls.V1_41_0);
+  }
+
+  public static <REQUEST> void setHttpClientExceptionEventExtractor(
+      InstrumenterBuilder<REQUEST, ?> builder) {
+    Experimental.setExceptionEventExtractor(
+        builder,
+        (logRecordBuilder, context, request) -> {
+          logRecordBuilder.setEventName("http.client.request.exception");
+          logRecordBuilder.setSeverity(Severity.WARN);
+        });
   }
 
   @CanIgnoreReturnValue

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/builder/internal/DefaultHttpServerInstrumenterBuilder.java

@@ -9,6 +9,7 @@
 
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.logs.Severity;
 import io.opentelemetry.context.propagation.TextMapGetter;
 import io.opentelemetry.instrumentation.api.incubator.config.internal.CommonConfig;
 import io.opentelemetry.instrumentation.api.incubator.semconv.http.HttpExperimentalAttributesExtractor;
@@ -230,7 +231,13 @@ public InstrumenterBuilder<REQUEST, RESPONSE> instrumenterBuilder() {
             .addAttributesExtractors(additionalExtractors)
             .addContextCustomizer(httpServerRouteBuilder.build())
             .addOperationMetrics(HttpServerMetrics.get())
-            .setSchemaUrl(SchemaUrls.V1_37_0);
+            .setSchemaUrl(SchemaUrls.V1_41_0);
+    Experimental.setExceptionEventExtractor(
+        builder,
+        (logRecordBuilder, context, request) -> {
+          logRecordBuilder.setEventName("http.server.request.exception");
+          logRecordBuilder.setSeverity(Severity.ERROR);
+        });
     if (emitExperimentalHttpServerTelemetry) {
       builder
           .addAttributesExtractor(HttpExperimentalAttributesExtractor.create(attributesGetter))

instrumentation-api/build.gradle.kts

@@ -44,4 +44,20 @@ tasks {
     jvmArgs("--add-opens=java.base/java.util=ALL-UNNAMED")
     jvmArgs("-XX:+IgnoreUnrecognizedVMOptions")
   }
+
+  val testExceptionSignalLogs by registering(Test::class) {
+    testClassesDirs = sourceSets.test.get().output.classesDirs
+    classpath = sourceSets.test.get().runtimeClasspath
+    jvmArgs("-Dotel.semconv.exception.signal.preview=logs")
+  }
+
+  val testExceptionSignalLogsDup by registering(Test::class) {
+    testClassesDirs = sourceSets.test.get().output.classesDirs
+    classpath = sourceSets.test.get().runtimeClasspath
+    jvmArgs("-Dotel.semconv.exception.signal.preview=logs/dup")
+  }
+
+  check {
+    dependsOn(testExceptionSignalLogs, testExceptionSignalLogsDup)
+  }
 }

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/Instrumenter.java

@@ -5,9 +5,14 @@
 
 package io.opentelemetry.instrumentation.api.instrumenter;
 
+import static io.opentelemetry.instrumentation.api.internal.SemconvExceptionSignal.emitExceptionAsLogs;
+import static io.opentelemetry.instrumentation.api.internal.SemconvExceptionSignal.emitExceptionAsSpanEvents;
 import static java.util.concurrent.TimeUnit.SECONDS;
 
 import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.logs.LogRecordBuilder;
+import io.opentelemetry.api.logs.Logger;
+import io.opentelemetry.api.logs.Severity;
 import io.opentelemetry.api.trace.Span;
 import io.opentelemetry.api.trace.SpanBuilder;
 import io.opentelemetry.api.trace.SpanKind;
@@ -18,6 +23,7 @@
 import io.opentelemetry.instrumentation.api.internal.InstrumenterAccess;
 import io.opentelemetry.instrumentation.api.internal.InstrumenterContext;
 import io.opentelemetry.instrumentation.api.internal.InstrumenterUtil;
+import io.opentelemetry.instrumentation.api.internal.InternalExceptionEventExtractor;
 import io.opentelemetry.instrumentation.api.internal.SupportabilityMetrics;
 import java.time.Instant;
 import javax.annotation.Nullable;
@@ -72,6 +78,7 @@ public static <REQUEST, RESPONSE> InstrumenterBuilder<REQUEST, RESPONSE> builder
 
   private final String instrumentationName;
   private final Tracer tracer;
+  @Nullable private final Logger logger;
   private final SpanNameExtractor<? super REQUEST> spanNameExtractor;
   private final SpanKindExtractor<? super REQUEST> spanKindExtractor;
   private final SpanStatusExtractor<? super REQUEST, ? super RESPONSE> spanStatusExtractor;
@@ -82,6 +89,7 @@ public static <REQUEST, RESPONSE> InstrumenterBuilder<REQUEST, RESPONSE> builder
   private final AttributesExtractor<? super REQUEST, ? super RESPONSE>[]
       operationListenerAttributesExtractors;
   private final ErrorCauseExtractor errorCauseExtractor;
+  @Nullable private final InternalExceptionEventExtractor<? super REQUEST> exceptionEventExtractor;
   private final boolean propagateOperationListenersToOnEnd;
   private final boolean enabled;
   private final SpanSuppressor spanSuppressor;
@@ -104,6 +112,17 @@ public static <REQUEST, RESPONSE> InstrumenterBuilder<REQUEST, RESPONSE> builder
     this.propagateOperationListenersToOnEnd = builder.propagateOperationListenersToOnEnd;
     this.enabled = builder.enabled;
     this.spanSuppressor = builder.buildSpanSuppressor();
+
+    if (emitExceptionAsLogs()) {
+      this.logger = builder.buildLogger();
+      this.exceptionEventExtractor =
+          builder.exceptionEventExtractor != null
+              ? builder.exceptionEventExtractor
+              : defaultExceptionEventExtractor(this.spanKindExtractor);
+    } else {
+      this.logger = null;
+      this.exceptionEventExtractor = null;
+    }
   }
 
   /**
@@ -260,7 +279,13 @@ private void doEnd(
 
     if (error != null) {
       error = errorCauseExtractor.extract(error);
-      span.recordException(error);
+      if (emitExceptionAsSpanEvents()) {
+        span.recordException(error);
+      }
+      // Exception logs are intentionally emitted even when the span is not recording.
+      if (emitExceptionAsLogs() && exceptionEventExtractor != null) {
+        emitExceptionLog(context, error, request, endTime);
+      }
     }
 
     UnsafeAttributes attributes = new UnsafeAttributes();
@@ -301,6 +326,40 @@ private void doEnd(
     }
   }
 
+  private void emitExceptionLog(
+      Context context, Throwable throwable, REQUEST request, @Nullable Instant endTime) {
+    if (logger == null || exceptionEventExtractor == null) {
+      // this condition is to keep nullaway happy
+      // doEnd already guards on exceptionEventExtractor != null, so this is unreachable
+      return;
+    }
+    LogRecordBuilder logRecordBuilder = logger.logRecordBuilder();
+    logRecordBuilder.setContext(context);
+    if (endTime != null) {
+      logRecordBuilder.setTimestamp(endTime);
+    }
+    exceptionEventExtractor.extract(logRecordBuilder, context, request);
+    logRecordBuilder.setException(throwable);
+    logRecordBuilder.emit();
+  }
+
+  // Per semconv
+  // (https://opentelemetry.io/docs/specs/semconv/general/recording-errors/#errors-in-logs),
+  // SERVER and CONSUMER spans should record exceptions with ERROR severity, while CLIENT and
+  // PRODUCER spans should use WARN.
+  private static <REQUEST> InternalExceptionEventExtractor<REQUEST> defaultExceptionEventExtractor(
+      SpanKindExtractor<? super REQUEST> spanKindExtractor) {
+    return (logRecordBuilder, context, request) -> {
+      logRecordBuilder.setEventName("exception");
+      SpanKind spanKind = spanKindExtractor.extract(request);
+      Severity severity =
+          (spanKind == SpanKind.SERVER || spanKind == SpanKind.CONSUMER)
+              ? Severity.ERROR
+              : Severity.WARN;
+      logRecordBuilder.setSeverity(severity);
+    };
+  }
+
   private static long getNanos(@Nullable Instant time) {
     if (time == null) {
       return System.nanoTime();

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java

@@ -14,6 +14,7 @@
 import io.opentelemetry.api.OpenTelemetry;
 import io.opentelemetry.api.incubator.ExtendedOpenTelemetry;
 import io.opentelemetry.api.incubator.config.DeclarativeConfigProperties;
+import io.opentelemetry.api.logs.LoggerBuilder;
 import io.opentelemetry.api.metrics.Meter;
 import io.opentelemetry.api.metrics.MeterBuilder;
 import io.opentelemetry.api.trace.SpanKind;
@@ -28,6 +29,7 @@
 import io.opentelemetry.instrumentation.api.internal.Experimental;
 import io.opentelemetry.instrumentation.api.internal.InstrumenterBuilderAccess;
 import io.opentelemetry.instrumentation.api.internal.InstrumenterUtil;
+import io.opentelemetry.instrumentation.api.internal.InternalExceptionEventExtractor;
 import io.opentelemetry.instrumentation.api.internal.InternalInstrumenterCustomizer;
 import io.opentelemetry.instrumentation.api.internal.InternalInstrumenterCustomizerProvider;
 import io.opentelemetry.instrumentation.api.internal.InternalInstrumenterCustomizerUtil;
@@ -71,6 +73,7 @@ public final class InstrumenterBuilder<REQUEST, RESPONSE> {
   SpanStatusExtractor<? super REQUEST, ? super RESPONSE> spanStatusExtractor =
       SpanStatusExtractor.getDefault();
   ErrorCauseExtractor errorCauseExtractor = ErrorCauseExtractor.getDefault();
+  @Nullable InternalExceptionEventExtractor<? super REQUEST> exceptionEventExtractor;
   boolean propagateOperationListenersToOnEnd = false;
   boolean enabled = true;
 
@@ -80,6 +83,10 @@ public final class InstrumenterBuilder<REQUEST, RESPONSE> {
             builder.operationListenerAttributesExtractors.add(
                 requireNonNull(
                     operationListenerAttributesExtractor, "operationListenerAttributesExtractor")));
+    Experimental.internalSetExceptionEventExtractor(
+        (builder, exceptionEventExtractor) ->
+            builder.exceptionEventExtractor =
+                requireNonNull(exceptionEventExtractor, "exceptionEventExtractor"));
   }
 
   InstrumenterBuilder(
@@ -314,6 +321,18 @@ Tracer buildTracer() {
     return tracerBuilder.build();
   }
 
+  io.opentelemetry.api.logs.Logger buildLogger() {
+    LoggerBuilder loggerBuilder = openTelemetry.getLogsBridge().loggerBuilder(instrumentationName);
+    if (instrumentationVersion != null) {
+      loggerBuilder.setInstrumentationVersion(instrumentationVersion);
+    }
+    String schemaUrl = getSchemaUrl();
+    if (schemaUrl != null) {
+      loggerBuilder.setSchemaUrl(schemaUrl);
+    }
+    return loggerBuilder.build();
+  }
+
   List<OperationListener> buildOperationListeners() {
     // just copy the listeners list if there are no metrics registered
     if (operationMetrics.isEmpty()) {

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/internal/Experimental.java

@@ -40,6 +40,10 @@ public final class Experimental {
   private static volatile BiConsumer<InstrumenterBuilder<?, ?>, AttributesExtractor<?, ?>>
       operationListenerAttributesExtractorAdder;
 
+  @Nullable
+  private static volatile BiConsumer<InstrumenterBuilder<?, ?>, InternalExceptionEventExtractor<?>>
+      exceptionEventExtractorSetter;
+
   private Experimental() {}
 
   /**
@@ -117,4 +121,24 @@ public static <REQUEST, RESPONSE> void internalAddOperationListenerAttributesExt
     Experimental.operationListenerAttributesExtractorAdder =
         (BiConsumer) operationListenerAttributesExtractorAdder;
   }
+
+  /**
+   * Sets the {@link InternalExceptionEventExtractor} that will determine the exception event name
+   * and severity. Only used when emitting exceptions as logs is enabled via the {@code
+   * otel.semconv.exception.signal.preview} flag.
+   */
+  public static <REQUEST> void setExceptionEventExtractor(
+      InstrumenterBuilder<REQUEST, ?> builder,
+      InternalExceptionEventExtractor<? super REQUEST> exceptionEventExtractor) {
+    if (exceptionEventExtractorSetter != null) {
+      exceptionEventExtractorSetter.accept(builder, exceptionEventExtractor);
+    }
+  }
+
+  @SuppressWarnings({"rawtypes", "unchecked"}) // we lose the generic type information
+  public static <REQUEST> void internalSetExceptionEventExtractor(
+      BiConsumer<InstrumenterBuilder<REQUEST, ?>, InternalExceptionEventExtractor<? super REQUEST>>
+          exceptionEventExtractorSetter) {
+    Experimental.exceptionEventExtractorSetter = (BiConsumer) exceptionEventExtractorSetter;
+  }
 }

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/internal/InternalExceptionEventExtractor.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.internal;
+
+import io.opentelemetry.api.logs.LogRecordBuilder;
+import io.opentelemetry.context.Context;
+
+/**
+ * Internal functional interface for exception event extraction.
+ *
+ * <p>This is temporary bridge API while exception event extraction is not available in the stable
+ * instrumentation API artifact. This interface should be revisited when a public API is added.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
+ */
+@FunctionalInterface
+public interface InternalExceptionEventExtractor<REQUEST> {
+
+  /**
+   * Populates the exception event {@link LogRecordBuilder} with the event name, severity, and any
+   * additional attributes for the given context and request.
+   */
+  void extract(LogRecordBuilder logRecordBuilder, Context context, REQUEST request);
+}