Add opt-in support for emitting exceptions as log signals

Author: trask

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.opt-in=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.opt-in=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

@@ -14,6 +14,7 @@
 import io.opentelemetry.instrumentation.api.incubator.config.internal.CommonConfig;
 import io.opentelemetry.instrumentation.api.incubator.semconv.http.HttpClientExperimentalMetrics;
 import io.opentelemetry.instrumentation.api.incubator.semconv.http.HttpClientServicePeerAttributesExtractor;
+import io.opentelemetry.instrumentation.api.incubator.semconv.http.HttpExceptionEventExtractors;
 import io.opentelemetry.instrumentation.api.incubator.semconv.http.HttpExperimentalAttributesExtractor;
 import io.opentelemetry.instrumentation.api.incubator.semconv.http.internal.HttpClientUrlTemplateUtil;
 import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
@@ -223,6 +224,7 @@ public Instrumenter<REQUEST, RESPONSE> build() {
             .addAttributesExtractors(additionalExtractors)
             .addOperationMetrics(HttpClientMetrics.get())
             .setSchemaUrl(SchemaUrls.V1_37_0);
+    Experimental.setExceptionEventExtractor(builder, HttpExceptionEventExtractors.client());
     if (emitExperimentalHttpClientTelemetry) {
       builder
           .addAttributesExtractor(HttpExperimentalAttributesExtractor.create(attributesGetter))

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

@@ -11,6 +11,7 @@
 import io.opentelemetry.api.OpenTelemetry;
 import io.opentelemetry.context.propagation.TextMapGetter;
 import io.opentelemetry.instrumentation.api.incubator.config.internal.CommonConfig;
+import io.opentelemetry.instrumentation.api.incubator.semconv.http.HttpExceptionEventExtractors;
 import io.opentelemetry.instrumentation.api.incubator.semconv.http.HttpExperimentalAttributesExtractor;
 import io.opentelemetry.instrumentation.api.incubator.semconv.http.HttpServerExperimentalMetrics;
 import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
@@ -19,6 +20,7 @@
 import io.opentelemetry.instrumentation.api.instrumenter.SpanKindExtractor;
 import io.opentelemetry.instrumentation.api.instrumenter.SpanNameExtractor;
 import io.opentelemetry.instrumentation.api.instrumenter.SpanStatusExtractor;
+import io.opentelemetry.instrumentation.api.internal.Experimental;
 import io.opentelemetry.instrumentation.api.semconv.http.HttpServerAttributesExtractor;
 import io.opentelemetry.instrumentation.api.semconv.http.HttpServerAttributesExtractorBuilder;
 import io.opentelemetry.instrumentation.api.semconv.http.HttpServerAttributesGetter;
@@ -215,6 +217,7 @@ public InstrumenterBuilder<REQUEST, RESPONSE> instrumenterBuilder() {
             .addContextCustomizer(httpServerRouteBuilder.build())
             .addOperationMetrics(HttpServerMetrics.get())
             .setSchemaUrl(SchemaUrls.V1_37_0);
+    Experimental.setExceptionEventExtractor(builder, HttpExceptionEventExtractors.server());
     if (emitExperimentalHttpServerTelemetry) {
       builder
           .addAttributesExtractor(HttpExperimentalAttributesExtractor.create(attributesGetter))

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/instrumenter/DefaultExceptionEventExtractor.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.incubator.instrumenter;
+
+import io.opentelemetry.api.logs.LogRecordBuilder;
+import io.opentelemetry.api.logs.Severity;
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.context.Context;
+import io.opentelemetry.instrumentation.api.instrumenter.LocalRootSpan;
+
+/**
+ * {@link ExceptionEventExtractor} that sets the given event name, using {@link Severity#ERROR} when
+ * the span is a local root, and {@link Severity#DEBUG} otherwise.
+ */
+final class DefaultExceptionEventExtractor<REQUEST> implements ExceptionEventExtractor<REQUEST> {
+
+  private final String eventName;
+
+  static <REQUEST> ExceptionEventExtractor<REQUEST> create(String eventName) {
+    return new DefaultExceptionEventExtractor<>(eventName);
+  }
+
+  private DefaultExceptionEventExtractor(String eventName) {
+    this.eventName = eventName;
+  }
+
+  @Override
+  public void extract(LogRecordBuilder logRecordBuilder, Context context, REQUEST request) {
+    logRecordBuilder.setEventName(eventName);
+    Span currentSpan = Span.fromContext(context);
+    Span localRootSpan = LocalRootSpan.fromContextOrNull(context);
+    if (currentSpan.equals(localRootSpan)) {
+      logRecordBuilder.setSeverity(Severity.ERROR);
+    } else {
+      logRecordBuilder.setSeverity(Severity.DEBUG);
+    }
+  }
+}

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/instrumenter/ExceptionEventExtractor.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.incubator.instrumenter;
+
+import io.opentelemetry.api.logs.LogRecordBuilder;
+import io.opentelemetry.api.logs.Severity;
+import io.opentelemetry.context.Context;
+import io.opentelemetry.instrumentation.api.internal.InternalExceptionEventExtractor;
+
+/**
+ * Extractor that populates the exception event {@link LogRecordBuilder} for a request. This allows
+ * instrumentations to set the event name, severity, and any additional attributes on the exception
+ * log event.
+ *
+ * <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 ExceptionEventExtractor<REQUEST> extends InternalExceptionEventExtractor<REQUEST> {
+
+  /**
+   * Returns an {@link ExceptionEventExtractor} that always sets the given event name and severity.
+   */
+  static <REQUEST> ExceptionEventExtractor<REQUEST> create(String eventName, Severity severity) {
+    return (logRecordBuilder, context, request) -> {
+      logRecordBuilder.setEventName(eventName);
+      logRecordBuilder.setSeverity(severity);
+    };
+  }
+
+  /**
+   * Returns an {@link ExceptionEventExtractor} that sets the given event name, with {@link
+   * Severity#ERROR} for local root spans and {@link Severity#DEBUG} otherwise.
+   */
+  static <REQUEST> ExceptionEventExtractor<REQUEST> create(String eventName) {
+    return DefaultExceptionEventExtractor.create(eventName);
+  }
+
+  /**
+   * Populates the exception event {@link LogRecordBuilder} with the event name, severity, and any
+   * additional attributes for the given context and request.
+   */
+  @Override
+  void extract(LogRecordBuilder logRecordBuilder, Context context, REQUEST request);
+}

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/db/DbExceptionEventExtractors.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.incubator.semconv.db;
+
+import io.opentelemetry.api.logs.Severity;
+import io.opentelemetry.instrumentation.api.incubator.instrumenter.ExceptionEventExtractor;
+
+/**
+ * {@link ExceptionEventExtractor} constants for DB client instrumentations.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
+ */
+public final class DbExceptionEventExtractors {
+
+  /** Exception event extractor for DB client spans. */
+  public static <REQUEST> ExceptionEventExtractor<REQUEST> client() {
+    return ExceptionEventExtractor.create("db.client.operation.exception", Severity.WARN);
+  }
+
+  private DbExceptionEventExtractors() {}
+}

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/genai/GenAiExceptionEventExtractors.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.incubator.semconv.genai;
+
+import io.opentelemetry.api.logs.Severity;
+import io.opentelemetry.instrumentation.api.incubator.instrumenter.ExceptionEventExtractor;
+
+/**
+ * {@link ExceptionEventExtractor} constants for GenAI client instrumentations.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
+ */
+public final class GenAiExceptionEventExtractors {
+
+  /** Exception event extractor for GenAI client spans. */
+  public static <REQUEST> ExceptionEventExtractor<REQUEST> client() {
+    return ExceptionEventExtractor.create("gen_ai.client.operation.exception", Severity.WARN);
+  }
+
+  private GenAiExceptionEventExtractors() {}
+}

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/http/HttpExceptionEventExtractors.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.incubator.semconv.http;
+
+import io.opentelemetry.api.logs.Severity;
+import io.opentelemetry.instrumentation.api.incubator.instrumenter.ExceptionEventExtractor;
+
+/**
+ * {@link ExceptionEventExtractor} constants for HTTP client and server instrumentations.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
+ */
+public final class HttpExceptionEventExtractors {
+
+  /** Exception event extractor for HTTP client spans. */
+  public static <REQUEST> ExceptionEventExtractor<REQUEST> client() {
+    return ExceptionEventExtractor.create("http.client.request.exception", Severity.WARN);
+  }
+
+  /** Exception event extractor for HTTP server spans. */
+  public static <REQUEST> ExceptionEventExtractor<REQUEST> server() {
+    return ExceptionEventExtractor.create("http.server.request.exception", Severity.ERROR);
+  }
+
+  private HttpExceptionEventExtractors() {}
+}

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingExceptionEventExtractors.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.incubator.semconv.messaging;
+
+import io.opentelemetry.api.logs.Severity;
+import io.opentelemetry.instrumentation.api.incubator.instrumenter.ExceptionEventExtractor;
+
+/**
+ * {@link ExceptionEventExtractor} constants for messaging instrumentations.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
+ */
+public final class MessagingExceptionEventExtractors {
+
+  /** Exception event extractor for messaging client operation spans. */
+  public static <REQUEST> ExceptionEventExtractor<REQUEST> client() {
+    return ExceptionEventExtractor.create("messaging.client.operation.exception", Severity.WARN);
+  }
+
+  /** Exception event extractor for messaging process spans. */
+  public static <REQUEST> ExceptionEventExtractor<REQUEST> process() {
+    return ExceptionEventExtractor.create("messaging.process.exception", Severity.ERROR);
+  }
+
+  private MessagingExceptionEventExtractors() {}
+}

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcExceptionEventExtractors.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.incubator.semconv.rpc;
+
+import io.opentelemetry.api.logs.Severity;
+import io.opentelemetry.instrumentation.api.incubator.instrumenter.ExceptionEventExtractor;
+
+/**
+ * {@link ExceptionEventExtractor} constants for RPC client and server instrumentations.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
+ */
+public final class RpcExceptionEventExtractors {
+
+  /** Exception event extractor for RPC client spans. */
+  public static <REQUEST> ExceptionEventExtractor<REQUEST> client() {
+    return ExceptionEventExtractor.create("rpc.client.call.exception", Severity.WARN);
+  }
+
+  /** Exception event extractor for RPC server spans. */
+  public static <REQUEST> ExceptionEventExtractor<REQUEST> server() {
+    return ExceptionEventExtractor.create("rpc.server.call.exception", Severity.ERROR);
+  }
+
+  private RpcExceptionEventExtractors() {}
+}