Emits lifecycle log lines with a configurable prefix (e.g. {@code CONFPLUGIN}, {@code CONFPLUGIN-A}) so one - * plugin — or two, for the multiple-plugins case — can be registered on a handler. Operation- and attempt-level hooks - * are filtered to step-type operations to match the requirement vocabulary. All lines are emitted from the real SDK - * plugin hooks; nothing is hand-rolled. + *
Emits lifecycle log lines with a configurable prefix (e.g. {@code CONFPLUGIN}, {@code CONFPLUGIN-A}) so one plugin
+ * — or two, for the multiple-plugins case — can be registered on a handler. Operation- and attempt-level hooks are
+ * filtered to step-type operations to match the requirement vocabulary. All lines are emitted from the real SDK plugin
+ * hooks; nothing is hand-rolled.
*/
@SuppressWarnings("deprecation")
public class ConformanceLoggingPlugin implements DurableExecutionPlugin {
diff --git a/conformance-tests/src/main/java/plugin/FaultyConformancePlugin.java b/conformance-tests/src/main/java/plugin/FaultyConformancePlugin.java
index 2b5e2306c..59811aae3 100644
--- a/conformance-tests/src/main/java/plugin/FaultyConformancePlugin.java
+++ b/conformance-tests/src/main/java/plugin/FaultyConformancePlugin.java
@@ -35,23 +35,23 @@ private String arnField() {
@Override
public void onInvocationStart(InvocationInfo info) {
this.executionArn = info.durableExecutionArn();
- System.out.println(String.format(
- "{\"plugin\": \"CONFPLUGIN-FAULTY\", \"hook\": \"invocation-start\"%s}", arnField()));
+ System.out.println(
+ String.format("{\"plugin\": \"CONFPLUGIN-FAULTY\", \"hook\": \"invocation-start\"%s}", arnField()));
throw new RuntimeException("faulty invocation-start");
}
@Override
public void onInvocationEnd(InvocationEndInfo info) {
- System.out.println(String.format(
- "{\"plugin\": \"CONFPLUGIN-FAULTY\", \"hook\": \"invocation-end\"%s}", arnField()));
+ System.out.println(
+ String.format("{\"plugin\": \"CONFPLUGIN-FAULTY\", \"hook\": \"invocation-end\"%s}", arnField()));
throw new RuntimeException("faulty invocation-end");
}
@Override
public void onOperationStart(OperationInfo info) {
if (isStep(info.type())) {
- System.out.println(String.format(
- "{\"plugin\": \"CONFPLUGIN-FAULTY\", \"hook\": \"operation-start\"%s}", arnField()));
+ System.out.println(
+ String.format("{\"plugin\": \"CONFPLUGIN-FAULTY\", \"hook\": \"operation-start\"%s}", arnField()));
throw new RuntimeException("faulty operation-start");
}
}
@@ -59,8 +59,8 @@ public void onOperationStart(OperationInfo info) {
@Override
public void onOperationEnd(OperationEndInfo info) {
if (isStep(info.type())) {
- System.out.println(String.format(
- "{\"plugin\": \"CONFPLUGIN-FAULTY\", \"hook\": \"operation-end\"%s}", arnField()));
+ System.out.println(
+ String.format("{\"plugin\": \"CONFPLUGIN-FAULTY\", \"hook\": \"operation-end\"%s}", arnField()));
throw new RuntimeException("faulty operation-end");
}
}
@@ -68,8 +68,8 @@ public void onOperationEnd(OperationEndInfo info) {
@Override
public void onUserFunctionStart(UserFunctionStartInfo info) {
if (isStep(info.type())) {
- System.out.println(String.format(
- "{\"plugin\": \"CONFPLUGIN-FAULTY\", \"hook\": \"attempt-start\"%s}", arnField()));
+ System.out.println(
+ String.format("{\"plugin\": \"CONFPLUGIN-FAULTY\", \"hook\": \"attempt-start\"%s}", arnField()));
throw new RuntimeException("faulty attempt-start");
}
}
@@ -77,8 +77,8 @@ public void onUserFunctionStart(UserFunctionStartInfo info) {
@Override
public void onUserFunctionEnd(UserFunctionEndInfo info) {
if (isStep(info.type())) {
- System.out.println(String.format(
- "{\"plugin\": \"CONFPLUGIN-FAULTY\", \"hook\": \"attempt-end\"%s}", arnField()));
+ System.out.println(
+ String.format("{\"plugin\": \"CONFPLUGIN-FAULTY\", \"hook\": \"attempt-end\"%s}", arnField()));
throw new RuntimeException("faulty attempt-end");
}
}
diff --git a/conformance-tests/src/main/java/plugin/PluginErrorIsolation.java b/conformance-tests/src/main/java/plugin/PluginErrorIsolation.java
index 59aeb80ce..0ff7aea7d 100644
--- a/conformance-tests/src/main/java/plugin/PluginErrorIsolation.java
+++ b/conformance-tests/src/main/java/plugin/PluginErrorIsolation.java
@@ -18,7 +18,9 @@ public class PluginErrorIsolation extends DurableHandler A single greeting step configured with {@link ConformanceLoggingPlugin}. The plugin's invocation-start hook logs
- * {@code first=true} before the handler runs and its invocation-end hook logs {@code status=SUCCEEDED} after the
- * result is finalized. The step body logs its running line via the context logger.
+ * {@code first=true} before the handler runs and its invocation-end hook logs {@code status=SUCCEEDED} after the result
+ * is finalized. The step body logs its running line via the context logger.
*/
@SuppressWarnings("deprecation")
public class PluginInvocationLifecycle extends DurableHandler A single greeting step configured with {@link ConformanceLoggingPlugin}. The plugin, filtering to step-type
- * operations, logs {@code operation-start} when the step's STARTED checkpoint is observed and
- * {@code operation-end status=SUCCEEDED} when the step reaches its terminal status.
+ * operations, logs {@code operation-start} when the step's STARTED checkpoint is observed and {@code operation-end
+ * status=SUCCEEDED} when the step reaches its terminal status.
*/
@SuppressWarnings("deprecation")
public class PluginOperationLifecycle extends DurableHandler A single step that always throws, configured with no retries and {@link ConformanceLoggingPlugin}. The plugin
- * logs {@code invocation-start first=true}; the step throws, no retry is attempted, and the plugin's invocation-end
- * hook fires with {@code status=FAILED}.
+ * A single step that always throws, configured with no retries and {@link ConformanceLoggingPlugin}. The plugin logs
+ * {@code invocation-start first=true}; the step throws, no retry is attempted, and the plugin's invocation-end hook
+ * fires with {@code status=FAILED}.
*/
@SuppressWarnings("deprecation")
public class PluginTerminalFailure extends DurableHandler {@link InvocationOtelPlugin#InvocationOtelPlugin()} uses the global provider initialized by the ADOT Java agent
+ * with deterministic span ID generation installed by the plugin's OpenTelemetry autoconfigure SPI.
+ */
+@ExampleTemplate(tracing = true, javaAgent = true)
+public class OtelXRayDefaultConstructorExample extends DurableHandler Exports spans through the ADOT Java agent global OpenTelemetry provider. Requires:
*
* Expected trace structure in X-Ray:
@@ -32,18 +30,12 @@
* └── transform attempt 1
*
*/
-@ExampleTemplate(tracing = true)
+@ExampleTemplate(tracing = true, javaAgent = true)
public class OtelXRayStepExample extends DurableHandler Exports spans via OTLP to the ADOT Lambda Layer collector. Requires:
+ * Exports spans through the ADOT Java agent global OpenTelemetry provider. Requires:
*
* Expected trace structure in X-Ray (all under one trace ID — backend propagates same Root):
*
* Workflow span behavior by provider:
+ *
+ * Trace ID resolution:
*
* Requires the ADOT Lambda Layer for trace export. Configure with:
*
* Note: Do NOT set {@code AWS_LAMBDA_EXEC_WRAPPER}. The collector extension runs independently. The wrapper would
- * attach the auto-instrumentation agent which creates a competing TracerProvider.
+ * When using {@link #InvocationOtelPlugin()}, the plugin requires
+ * {@code OtelPluginAutoConfigurationCustomizerProvider} to have been installed by the OpenTelemetry Java agent and uses
+ * the global provider directly.
+ *
+ * X-Ray console limitation: In the X-Ray "Segments Timeline" ungrouped view, the plugin's spans (Invocation,
+ * operation, attempt) do not appear as nested subsegments of the Lambda platform segment. This is a known limitation of
+ * the OTLP-to-X-Ray conversion: the ADOT collector cannot attach OTLP-exported spans as subsegments of the Lambda
+ * service's native X-Ray segment because that segment is created outside the OTLP pipeline. Use the "Group by nodes"
+ * view to see the full span hierarchy correctly — it stitches all spans together by trace ID and parent-child
+ * relationships regardless of segment boundaries.
*
* Thread-safe: uses {@link ConcurrentHashMap} for span/scope storage since the SDK runs user code on multiple
* threads.
@@ -77,7 +100,7 @@ public class InvocationOtelPlugin implements DurableExecutionPlugin {
private static final String INSTRUMENTATION_NAME = "aws-durable-execution-sdk-java";
private static final String DEFAULT_WORKFLOW_SPAN_NAME = "Workflow";
- private final SdkTracerProvider tracerProvider;
+ private final SdkTracerProvider sdkTracerProvider;
private final Tracer tracer;
private final DeterministicIdGenerator idGenerator;
private final ContextExtractor contextExtractor;
@@ -105,12 +128,13 @@ public class InvocationOtelPlugin implements DurableExecutionPlugin {
* Uses the provided tracer provider builder. Customers configure exporters and span processors on the builder —
* the plugin handles ID generation.
*
- * For ADOT layer usage, configure with an OTLP exporter:
+ * For ADOT Java agent usage, prefer {@link #InvocationOtelPlugin()} with the plugin jar configured through
+ * {@code OTEL_JAVAAGENT_EXTENSIONS}. Use this builder constructor when you want to own the exporter pipeline:
*
* Uses {@code GlobalOpenTelemetry} directly and assumes deterministic ID generation was installed by
+ * {@code OtelPluginAutoConfigurationCustomizerProvider}.
+ */
+ public InvocationOtelPlugin() {
+ this(getDefaultTracerProvider(), createDefaultIdGenerator());
+ }
+
/**
* Creates an OTel plugin with a custom context extractor, MDC enabled.
*
@@ -156,17 +190,24 @@ public InvocationOtelPlugin(
String workflowSpanName) {
this.idGenerator = new DeterministicIdGenerator();
- // Set service.name to "invocation" for the exported spans' resource.
- var resource = Resource.create(Attributes.of(ServiceAttributes.SERVICE_NAME, "invocation"));
- tracerProviderBuilder.addResource(resource);
-
- this.tracerProvider = tracerProviderBuilder.setIdGenerator(idGenerator).build();
- this.tracer = tracerProvider.get(INSTRUMENTATION_NAME);
+ this.sdkTracerProvider =
+ tracerProviderBuilder.setIdGenerator(idGenerator).build();
+ this.tracer = sdkTracerProvider.get(INSTRUMENTATION_NAME);
this.contextExtractor = contextExtractor;
this.enableMdc = enableMdc;
this.workflowSpanName = workflowSpanName != null ? workflowSpanName : DEFAULT_WORKFLOW_SPAN_NAME;
}
+ private InvocationOtelPlugin(TracerProvider tracerProvider, DeterministicIdGenerator idGenerator) {
+ this.idGenerator = idGenerator;
+ this.sdkTracerProvider = getSdkTracerProviderForFlush(tracerProvider);
+ this.tracer = tracerProvider.get(INSTRUMENTATION_NAME);
+
+ this.contextExtractor = new XRayContextExtractor();
+ this.enableMdc = true;
+ this.workflowSpanName = DEFAULT_WORKFLOW_SPAN_NAME;
+ }
+
// ─── Invocation hooks ────────────────────────────────────────────────
@Override
@@ -178,10 +219,15 @@ public void onInvocationStart(InvocationInfo info) {
// Extract trace context from environment (X-Ray header)
var extractedContext = contextExtractor.extract();
+ if (extractedContext == null) {
+ extractedContext = extractCurrentSpanContext();
+ }
if (extractedContext != null) {
// Use the X-Ray trace ID — backend propagates same Root across all invocations
idGenerator.setExtractedTraceId(extractedContext.traceId());
+ } else {
+ idGenerator.setExtractedTraceId(null);
}
// If no extracted context, idGenerator falls back to ARN-derived trace ID
@@ -200,8 +246,8 @@ public void onInvocationStart(InvocationInfo info) {
// Determine parent context for the invocation span.
Context parentContext;
if (extractedContext != null && extractedContext.parentSpanId() != null) {
- // X-Ray header has parent — create the invocation span as a child of that segment.
- // This connects our OTLP-exported spans to the Lambda service's X-Ray segments.
+ // Reconstruct a remote parent from the extracted trace context (X-Ray header or current span).
+ // This connects plugin spans to the Lambda service's X-Ray segments.
var parentSpanContext = SpanContext.createFromRemoteParent(
extractedContext.traceId(),
extractedContext.parentSpanId(),
@@ -224,10 +270,22 @@ public void onInvocationStart(InvocationInfo info) {
}
invocationSpan = spanBuilder.startSpan();
+
+ // Inject MDC on the handler thread so handler-level logs (between steps) have trace context.
+ // This runs on the same thread as context.getLogger() calls in the handler.
+ if (enableMdc) {
+ var traceId = idGenerator.generateTraceId();
+ MDC.put(MdcSpanEnricher.MDC_TRACE_ID, traceId);
+ }
}
@Override
public void onInvocationEnd(InvocationEndInfo info) {
+ // Clear invocation-level MDC (set in onInvocationStart on the handler thread)
+ if (enableMdc) {
+ MdcSpanEnricher.clear();
+ }
+
if (invocationSpan == null) return;
// End still-open operation spans without stamping a status — no terminal
@@ -301,10 +359,12 @@ public void onInvocationEnd(InvocationEndInfo info) {
workflowSpan = null;
}
- // Flush spans before Lambda freezes
- var flushResult = tracerProvider.forceFlush().join(5, java.util.concurrent.TimeUnit.SECONDS);
- if (!flushResult.isSuccess()) {
- logger.warn("OTel span flush failed or timed out — some spans may be lost");
+ if (sdkTracerProvider != null) {
+ // Flush spans before Lambda freezes
+ var flushResult = sdkTracerProvider.forceFlush().join(5, TimeUnit.SECONDS);
+ if (!flushResult.isSuccess()) {
+ logger.warn("OTel span flush failed or timed out — some spans may be lost");
+ }
}
}
@@ -489,9 +549,9 @@ public void onUserFunctionEnd(UserFunctionEndInfo info) {
scope.close();
}
- // Clear MDC after user function completes
+ // Clear span-level MDC after user function completes (keep trace_id for handler-level logs between steps)
if (enableMdc) {
- MdcSpanEnricher.clear();
+ MDC.remove(MdcSpanEnricher.MDC_SPAN_ID);
}
// CONTEXT operations don't have attempt spans — scope cleanup is all we need
@@ -572,4 +632,82 @@ private static String attemptSpanName(String type, String subType, String name,
private static String attemptKey(String operationId, Integer attempt) {
return operationId + "-" + (attempt != null ? attempt : "ctx");
}
+
+ private static ExtractedContext extractCurrentSpanContext() {
+ var spanContext = Span.current().getSpanContext();
+ if (!spanContext.isValid()) {
+ return null;
+ }
+ return new ExtractedContext(spanContext.getTraceId(), spanContext.getSpanId());
+ }
+
+ private static TracerProvider getDefaultTracerProvider() {
+ validateAutoConfigurationCustomizerProviderInstalled();
+
+ var globalTracerProvider = GlobalOpenTelemetry.getTracerProvider();
+ if (globalTracerProvider == TracerProvider.noop()) {
+ throw new IllegalStateException("InvocationOtelPlugin() requires GlobalOpenTelemetry to be initialized by "
+ + "OtelPluginAutoConfigurationCustomizerProvider through the OpenTelemetry Java agent.");
+ }
+ logger.info(
+ "InvocationOtelPlugin initialized from existing GlobalOpenTelemetry tracer provider {}; assuming "
+ + "deterministic span IDs were installed through AutoConfigurationCustomizerProvider",
+ globalTracerProvider.getClass().getName());
+ return globalTracerProvider;
+ }
+
+ private static DeterministicIdGenerator createDefaultIdGenerator() {
+ // This is intentionally a separate instance from the SPI provider's generator. The Java agent extension and
+ // application may load this plugin in different class loaders, so DeterministicIdGenerator bridges invocation
+ // state through system properties that the SPI-installed generator can read when spans are started.
+ return new DeterministicIdGenerator();
+ }
+
+ private static void validateAutoConfigurationCustomizerProviderInstalled() {
+ if (OtelPluginAutoConfigurationState.isInstalled()) {
+ return;
+ }
+ throw new IllegalStateException(
+ "InvocationOtelPlugin() requires OtelPluginAutoConfigurationCustomizerProvider to be installed by the "
+ + "OpenTelemetry Java agent. Package this plugin jar as an agent extension and set "
+ + "OTEL_JAVAAGENT_EXTENSIONS or -Dotel.javaagent.extensions to that jar before constructing "
+ + "InvocationOtelPlugin(). "
+ + javaAgentExtensionsDiagnostic());
+ }
+
+ private static String javaAgentExtensionsDiagnostic() {
+ var propertyValue = System.getProperty("otel.javaagent.extensions");
+ var environmentValue = System.getenv("OTEL_JAVAAGENT_EXTENSIONS");
+ var configuredPath = propertyValue != null ? propertyValue : environmentValue;
+ return "otel.javaagent.extensions="
+ + valueOrUnset(propertyValue)
+ + ", OTEL_JAVAAGENT_EXTENSIONS="
+ + valueOrUnset(environmentValue)
+ + ", configured extension path exists="
+ + extensionPathExists(configuredPath);
+ }
+
+ private static String valueOrUnset(String value) {
+ return value != null ? value : " When used with structured logging (Log4j2 JSON, Logback JSON), these MDC fields appear in every log line, enabling
- * tools like CloudWatch Logs Insights and Datadog to correlate logs with traces.
+ * tools like CloudWatch Application Signals and Datadog to correlate logs with traces.
*
* MDC keys injected:
*
*
*
*
*
*
*
*
* Trace (single trace ID across both invocations)
- * ├── durable.invocation (invocation 1)
- * │ ├── durable.step:before-wait
- * │ │ └── durable.step:before-wait [attempt 1]
- * │ └── durable.wait:pause (ended as PENDING)
- * └── durable.invocation (invocation 2)
- * ├── durable.wait:pause (completed)
- * └── durable.step:after-wait
- * └── durable.step:after-wait [attempt 1]
+ * ├── invocation (invocation 1)
+ * │ ├── before-wait
+ * │ │ └── before-wait attempt 1
+ * │ └── pause (ended as PENDING)
+ * └── invocation (invocation 2)
+ * ├── pause (completed)
+ * └── after-wait
+ * └── after-wait attempt 1
*
*/
-@ExampleTemplate(tracing = true)
+@ExampleTemplate(tracing = true, javaAgent = true)
public class OtelXRayWaitExample extends DurableHandler
+ *
+ *
*
@@ -58,12 +73,20 @@
*
- *
*
- * {@code
- * var otlpExporter = OtlpGrpcSpanExporter.getDefault(); // sends to localhost:4317
+ * var exporter = LoggingSpanExporter.create();
* var plugin = new InvocationOtelPlugin(
- * SdkTracerProvider.builder().addSpanProcessor(SimpleSpanProcessor.create(otlpExporter)));
+ * SdkTracerProvider.builder().addSpanProcessor(SimpleSpanProcessor.create(exporter)));
* }
*
* @param tracerProviderBuilder the tracer provider builder (ID generator will be overridden)
@@ -119,6 +143,16 @@ public InvocationOtelPlugin(SdkTracerProviderBuilder tracerProviderBuilder) {
this(tracerProviderBuilder, new XRayContextExtractor(), true);
}
+ /**
+ * Creates an OTel plugin with default settings: X-Ray context extraction and MDC enabled.
+ *
+ *
- *
*
@@ -28,8 +28,8 @@
@Deprecated
public final class MdcSpanEnricher {
- public static final String MDC_TRACE_ID = "traceId";
- public static final String MDC_SPAN_ID = "spanId";
+ public static final String MDC_TRACE_ID = "trace_id";
+ public static final String MDC_SPAN_ID = "span_id";
public static final String MDC_TRACE_SAMPLED = "traceSampled";
private MdcSpanEnricher() {}
diff --git a/otel-plugin/src/main/java/software/amazon/lambda/durable/otel/OtelPluginAutoConfigurationCustomizerProvider.java b/otel-plugin/src/main/java/software/amazon/lambda/durable/otel/OtelPluginAutoConfigurationCustomizerProvider.java
new file mode 100644
index 000000000..23ac19ecd
--- /dev/null
+++ b/otel-plugin/src/main/java/software/amazon/lambda/durable/otel/OtelPluginAutoConfigurationCustomizerProvider.java
@@ -0,0 +1,23 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.otel;
+
+import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizer;
+import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider;
+
+/**
+ * Installs the durable-execution ID generator when the OpenTelemetry Java agent auto-configures the SDK.
+ *
+ * @deprecated This is a preview API that is experimental and may be changed or removed in future releases.
+ */
+@Deprecated
+public final class OtelPluginAutoConfigurationCustomizerProvider implements AutoConfigurationCustomizerProvider {
+
+ private static final DeterministicIdGenerator ID_GENERATOR = new DeterministicIdGenerator();
+
+ @Override
+ public void customize(AutoConfigurationCustomizer autoConfiguration) {
+ OtelPluginAutoConfigurationState.markInstalled();
+ autoConfiguration.addTracerProviderCustomizer((builder, config) -> builder.setIdGenerator(ID_GENERATOR));
+ }
+}
diff --git a/otel-plugin/src/main/java/software/amazon/lambda/durable/otel/OtelPluginAutoConfigurationState.java b/otel-plugin/src/main/java/software/amazon/lambda/durable/otel/OtelPluginAutoConfigurationState.java
new file mode 100644
index 000000000..765489b69
--- /dev/null
+++ b/otel-plugin/src/main/java/software/amazon/lambda/durable/otel/OtelPluginAutoConfigurationState.java
@@ -0,0 +1,23 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.otel;
+
+final class OtelPluginAutoConfigurationState {
+
+ private static final String INSTALLED_PROPERTY =
+ "software.amazon.lambda.durable.otel.autoConfigurationCustomizerProviderInstalled";
+
+ private OtelPluginAutoConfigurationState() {}
+
+ static boolean isInstalled() {
+ return Boolean.getBoolean(INSTALLED_PROPERTY);
+ }
+
+ static void markInstalled() {
+ System.setProperty(INSTALLED_PROPERTY, Boolean.TRUE.toString());
+ }
+
+ static void resetInstalledForTest() {
+ System.clearProperty(INSTALLED_PROPERTY);
+ }
+}
diff --git a/otel-plugin/src/main/resources/META-INF/services/io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider b/otel-plugin/src/main/resources/META-INF/services/io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider
new file mode 100644
index 000000000..3aa2fb591
--- /dev/null
+++ b/otel-plugin/src/main/resources/META-INF/services/io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider
@@ -0,0 +1 @@
+software.amazon.lambda.durable.otel.OtelPluginAutoConfigurationCustomizerProvider
diff --git a/otel-plugin/src/test/java/io/opentelemetry/javaagent/testing/FakeJavaAgentTracerProvider.java b/otel-plugin/src/test/java/io/opentelemetry/javaagent/testing/FakeJavaAgentTracerProvider.java
new file mode 100644
index 000000000..db99b5bdb
--- /dev/null
+++ b/otel-plugin/src/test/java/io/opentelemetry/javaagent/testing/FakeJavaAgentTracerProvider.java
@@ -0,0 +1,31 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package io.opentelemetry.javaagent.testing;
+
+import io.opentelemetry.api.trace.Tracer;
+import io.opentelemetry.api.trace.TracerBuilder;
+import io.opentelemetry.api.trace.TracerProvider;
+
+public final class FakeJavaAgentTracerProvider implements TracerProvider {
+
+ private final TracerProvider delegate;
+
+ public FakeJavaAgentTracerProvider(TracerProvider agentTracerProvider) {
+ this.delegate = agentTracerProvider;
+ }
+
+ @Override
+ public Tracer get(String instrumentationName) {
+ return delegate.get(instrumentationName);
+ }
+
+ @Override
+ public Tracer get(String instrumentationName, String instrumentationVersion) {
+ return delegate.get(instrumentationName, instrumentationVersion);
+ }
+
+ @Override
+ public TracerBuilder tracerBuilder(String instrumentationScopeName) {
+ return delegate.tracerBuilder(instrumentationScopeName);
+ }
+}
diff --git a/otel-plugin/src/test/java/software/amazon/lambda/durable/otel/DeterministicIdGeneratorTest.java b/otel-plugin/src/test/java/software/amazon/lambda/durable/otel/DeterministicIdGeneratorTest.java
index bc1a5a90d..6133a3ddb 100644
--- a/otel-plugin/src/test/java/software/amazon/lambda/durable/otel/DeterministicIdGeneratorTest.java
+++ b/otel-plugin/src/test/java/software/amazon/lambda/durable/otel/DeterministicIdGeneratorTest.java
@@ -4,6 +4,7 @@
import static org.junit.jupiter.api.Assertions.*;
+import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
@@ -13,9 +14,15 @@ class DeterministicIdGeneratorTest {
@BeforeEach
void setUp() {
+ DeterministicIdGenerator.clearSharedStateForTest();
generator = new DeterministicIdGenerator();
}
+ @AfterEach
+ void tearDown() {
+ DeterministicIdGenerator.clearSharedStateForTest();
+ }
+
@Test
void generateTraceId_withoutArn_returnsRandom() {
var id1 = generator.generateTraceId();
@@ -120,6 +127,18 @@ void generateSpanIdForOperation_isDeterministic() {
assertEquals(id1, id2);
}
+ @Test
+ void generatedIds_areSharedAcrossGeneratorInstances() {
+ var pluginGenerator = new DeterministicIdGenerator();
+ var agentGenerator = new DeterministicIdGenerator();
+
+ pluginGenerator.setDurableExecutionArn("arn:exec1");
+ pluginGenerator.setNextSpanOperationId("op-1");
+
+ assertEquals(pluginGenerator.generateTraceId(), agentGenerator.generateTraceId());
+ assertEquals(pluginGenerator.generateSpanIdForOperation("op-1"), agentGenerator.generateSpanId());
+ }
+
@Test
void traceId_isValidHex() {
generator.setDurableExecutionArn("arn:exec1");
diff --git a/otel-plugin/src/test/java/software/amazon/lambda/durable/otel/InvocationOtelPluginIntegrationTest.java b/otel-plugin/src/test/java/software/amazon/lambda/durable/otel/InvocationOtelPluginIntegrationTest.java
index c6961a827..d4e85c241 100644
--- a/otel-plugin/src/test/java/software/amazon/lambda/durable/otel/InvocationOtelPluginIntegrationTest.java
+++ b/otel-plugin/src/test/java/software/amazon/lambda/durable/otel/InvocationOtelPluginIntegrationTest.java
@@ -4,7 +4,12 @@
import static org.junit.jupiter.api.Assertions.*;
+import io.opentelemetry.api.GlobalOpenTelemetry;
+import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.StatusCode;
+import io.opentelemetry.context.propagation.ContextPropagators;
+import io.opentelemetry.javaagent.testing.FakeJavaAgentTracerProvider;
+import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.testing.exporter.InMemorySpanExporter;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.data.SpanData;
@@ -13,6 +18,7 @@
import java.time.Duration;
import java.util.List;
import java.util.concurrent.atomic.AtomicInteger;
+import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import software.amazon.awssdk.services.lambda.model.ErrorObject;
@@ -34,6 +40,8 @@ class InvocationOtelPluginIntegrationTest {
@BeforeEach
void setUp() {
+ DeterministicIdGenerator.clearSharedStateForTest();
+ OtelPluginAutoConfigurationState.resetInstalledForTest();
spanExporter = InMemorySpanExporter.create();
var plugin = new InvocationOtelPlugin(
@@ -44,6 +52,13 @@ void setUp() {
otelConfig = DurableConfig.builder().withPlugins(plugin).build();
}
+ @AfterEach
+ void tearDown() {
+ GlobalOpenTelemetry.resetForTest();
+ DeterministicIdGenerator.clearSharedStateForTest();
+ OtelPluginAutoConfigurationState.resetInstalledForTest();
+ }
+
@Test
void simpleStep_producesInvocationAndOperationAndAttemptSpans() {
var runner = LocalDurableTestRunner.create(
@@ -511,4 +526,71 @@ void waitForCondition_producesSpansWithAttempts() {
"Should have waitForCondition span. Got: "
+ spans.stream().map(SpanData::getName).toList());
}
+
+ @Test
+ void defaultConstructor_usesGlobalSdkTracerProviderDirectly() {
+ OtelPluginAutoConfigurationState.markInstalled();
+ GlobalOpenTelemetry.resetForTest();
+ var globalExporter = InMemorySpanExporter.create();
+ var globalTracerProvider = SdkTracerProvider.builder()
+ .addSpanProcessor(SimpleSpanProcessor.create(globalExporter))
+ .build();
+ OpenTelemetrySdk.builder().setTracerProvider(globalTracerProvider).buildAndRegisterGlobal();
+
+ var defaultConfig =
+ DurableConfig.builder().withPlugins(new InvocationOtelPlugin()).build();
+ var runner = LocalDurableTestRunner.create(
+ String.class,
+ (input, ctx) -> ctx.step("global-step", String.class, stepCtx -> "Hello " + input),
+ defaultConfig);
+
+ var result = runner.runUntilComplete("World");
+ assertEquals(ExecutionStatus.SUCCEEDED, result.getStatus());
+
+ var spans = globalExporter.getFinishedSpanItems();
+ assertTrue(spans.size() >= 4, "Expected at least 4 spans, got " + spans.size());
+ assertSpanExists(spans, "Invocation");
+ assertSpanExists(spans, "global-step");
+ assertSpanExists(spans, "global-step attempt 1");
+ }
+
+ @Test
+ void defaultConstructor_usesJavaAgentGlobalTracerProviderDirectly_withSeparateAutoConfiguredIdGenerator() {
+ OtelPluginAutoConfigurationState.markInstalled();
+ GlobalOpenTelemetry.resetForTest();
+ var globalExporter = InMemorySpanExporter.create();
+ var javaAgentIdGenerator = new DeterministicIdGenerator();
+ var sdkTracerProvider = SdkTracerProvider.builder()
+ .setIdGenerator(javaAgentIdGenerator)
+ .addSpanProcessor(SimpleSpanProcessor.create(globalExporter))
+ .build();
+ var javaAgentTracerProvider = new FakeJavaAgentTracerProvider(sdkTracerProvider);
+ GlobalOpenTelemetry.set(new OpenTelemetry() {
+ @Override
+ public io.opentelemetry.api.trace.TracerProvider getTracerProvider() {
+ return javaAgentTracerProvider;
+ }
+
+ @Override
+ public ContextPropagators getPropagators() {
+ return ContextPropagators.noop();
+ }
+ });
+
+ var defaultConfig =
+ DurableConfig.builder().withPlugins(new InvocationOtelPlugin()).build();
+ var runner = LocalDurableTestRunner.create(
+ String.class,
+ (input, ctx) -> ctx.step("javaagent-step", String.class, stepCtx -> "Hello " + input),
+ defaultConfig);
+
+ var result = runner.runUntilComplete("World");
+ assertEquals(ExecutionStatus.SUCCEEDED, result.getStatus());
+
+ var spans = globalExporter.getFinishedSpanItems();
+ assertTrue(spans.size() >= 4, "Expected at least 4 spans, got " + spans.size());
+ assertSpanExists(spans, "Invocation");
+ assertSpanExists(spans, "javaagent-step");
+ assertSpanExists(spans, "javaagent-step attempt 1");
+ }
}
diff --git a/otel-plugin/src/test/java/software/amazon/lambda/durable/otel/InvocationOtelPluginTest.java b/otel-plugin/src/test/java/software/amazon/lambda/durable/otel/InvocationOtelPluginTest.java
index 2536d0ad3..39971f667 100644
--- a/otel-plugin/src/test/java/software/amazon/lambda/durable/otel/InvocationOtelPluginTest.java
+++ b/otel-plugin/src/test/java/software/amazon/lambda/durable/otel/InvocationOtelPluginTest.java
@@ -3,16 +3,38 @@
package software.amazon.lambda.durable.otel;
import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+import io.opentelemetry.api.GlobalOpenTelemetry;
+import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.api.trace.SpanContext;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.api.trace.StatusCode;
+import io.opentelemetry.api.trace.TraceFlags;
+import io.opentelemetry.api.trace.TraceState;
+import io.opentelemetry.context.propagation.ContextPropagators;
+import io.opentelemetry.javaagent.testing.FakeJavaAgentTracerProvider;
+import io.opentelemetry.sdk.OpenTelemetrySdk;
+import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizer;
+import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider;
+import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
import io.opentelemetry.sdk.testing.exporter.InMemorySpanExporter;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
+import io.opentelemetry.sdk.trace.SdkTracerProviderBuilder;
import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor;
import java.time.Instant;
+import java.util.ServiceLoader;
+import java.util.concurrent.TimeUnit;
+import java.util.function.BiFunction;
+import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
import software.amazon.lambda.durable.execution.SuspendExecutionException;
import software.amazon.lambda.durable.plugin.*;
@@ -23,6 +45,8 @@ class InvocationOtelPluginTest {
@BeforeEach
void setUp() {
+ DeterministicIdGenerator.clearSharedStateForTest();
+ OtelPluginAutoConfigurationState.resetInstalledForTest();
spanExporter = InMemorySpanExporter.create();
plugin = new InvocationOtelPlugin(
@@ -31,6 +55,167 @@ void setUp() {
false);
}
+ @AfterEach
+ void tearDown() {
+ GlobalOpenTelemetry.resetForTest();
+ DeterministicIdGenerator.clearSharedStateForTest();
+ OtelPluginAutoConfigurationState.resetInstalledForTest();
+ }
+
+ @Test
+ void defaultConstructor_throwsWhenAutoConfigurationCustomizerProviderIsNotInstalled() {
+ GlobalOpenTelemetry.resetForTest();
+
+ var error = assertThrows(IllegalStateException.class, InvocationOtelPlugin::new);
+
+ assertTrue(error.getMessage().contains("OtelPluginAutoConfigurationCustomizerProvider"));
+ assertTrue(error.getMessage().contains("OTEL_JAVAAGENT_EXTENSIONS"));
+ }
+
+ @Test
+ void defaultConstructor_throwsWhenGlobalOpenTelemetryIsNotInitializedBySpi() {
+ OtelPluginAutoConfigurationState.markInstalled();
+ GlobalOpenTelemetry.resetForTest();
+
+ var error = assertThrows(IllegalStateException.class, InvocationOtelPlugin::new);
+
+ assertTrue(error.getMessage().contains("GlobalOpenTelemetry"));
+ assertTrue(error.getMessage().contains("OtelPluginAutoConfigurationCustomizerProvider"));
+ }
+
+ @Test
+ void defaultConstructor_usesGlobalSdkTracerProviderDirectly() {
+ OtelPluginAutoConfigurationState.markInstalled();
+ GlobalOpenTelemetry.resetForTest();
+ var globalExporter = InMemorySpanExporter.create();
+ var globalTracerProvider = SdkTracerProvider.builder()
+ .addSpanProcessor(SimpleSpanProcessor.create(globalExporter))
+ .build();
+ OpenTelemetrySdk.builder().setTracerProvider(globalTracerProvider).buildAndRegisterGlobal();
+
+ var defaultPlugin = new InvocationOtelPlugin();
+ defaultPlugin.onInvocationStart(new InvocationInfo("req-1", "arn:exec1", true, Instant.now()));
+ defaultPlugin.onOperationStart(
+ new OperationInfo("op-1", "step", "STEP", "Step", null, Instant.now(), null, false));
+ defaultPlugin.onOperationEnd(new OperationEndInfo(
+ "op-1", "step", "STEP", "Step", null, Instant.now(), Instant.now(), "SUCCEEDED", null, false, null));
+ defaultPlugin.onInvocationEnd(
+ new InvocationEndInfo("req-1", "arn:exec1", true, InvocationStatus.SUCCEEDED, null));
+
+ var spans = globalExporter.getFinishedSpanItems();
+ // Plugin creates Workflow + Invocation + operation spans
+ assertEquals(3, spans.size());
+ assertTrue(spans.stream().anyMatch(span -> span.getName().equals("step")));
+ }
+
+ @Test
+ void defaultConstructor_usesJavaAgentGlobalTracerProviderDirectly_withSeparateAutoConfiguredIdGenerator() {
+ OtelPluginAutoConfigurationState.markInstalled();
+ GlobalOpenTelemetry.resetForTest();
+ var globalExporter = InMemorySpanExporter.create();
+ var javaAgentIdGenerator = new DeterministicIdGenerator();
+ var sdkTracerProvider = SdkTracerProvider.builder()
+ .setIdGenerator(javaAgentIdGenerator)
+ .addSpanProcessor(SimpleSpanProcessor.create(globalExporter))
+ .build();
+ var javaAgentTracerProvider = new FakeJavaAgentTracerProvider(sdkTracerProvider);
+ GlobalOpenTelemetry.set(new OpenTelemetry() {
+ @Override
+ public io.opentelemetry.api.trace.TracerProvider getTracerProvider() {
+ return javaAgentTracerProvider;
+ }
+
+ @Override
+ public ContextPropagators getPropagators() {
+ return ContextPropagators.noop();
+ }
+ });
+
+ var defaultPlugin = new InvocationOtelPlugin();
+ defaultPlugin.onInvocationStart(new InvocationInfo("req-1", "arn:exec1", true, Instant.now()));
+ defaultPlugin.onOperationStart(
+ new OperationInfo("op-1", "step", "STEP", "Step", null, Instant.now(), null, false));
+ defaultPlugin.onOperationEnd(new OperationEndInfo(
+ "op-1", "step", "STEP", "Step", null, Instant.now(), Instant.now(), "SUCCEEDED", null, false, null));
+ defaultPlugin.onInvocationEnd(
+ new InvocationEndInfo("req-1", "arn:exec1", true, InvocationStatus.SUCCEEDED, null));
+
+ var spans = globalExporter.getFinishedSpanItems();
+ // Plugin creates Workflow + Invocation + operation spans
+ assertEquals(3, spans.size());
+ assertTrue(spans.stream().anyMatch(span -> span.getName().equals("step")));
+ var expectedIds = new DeterministicIdGenerator();
+ expectedIds.setDurableExecutionArn("arn:exec1");
+ var stepSpan = spans.stream()
+ .filter(span -> span.getName().equals("step"))
+ .findFirst()
+ .orElseThrow();
+ assertEquals(expectedIds.generateSpanIdForOperation("op-1"), stepSpan.getSpanId());
+ }
+
+ @Test
+ void autoConfigurationCustomizerProvider_installsSharedDeterministicIdGenerator() {
+ OtelPluginAutoConfigurationState.resetInstalledForTest();
+ var exporter = InMemorySpanExporter.create();
+ var autoConfiguration = mock(AutoConfigurationCustomizer.class);
+ when(autoConfiguration.addTracerProviderCustomizer(any())).thenReturn(autoConfiguration);
+
+ new OtelPluginAutoConfigurationCustomizerProvider().customize(autoConfiguration);
+ assertTrue(OtelPluginAutoConfigurationState.isInstalled());
+
+ @SuppressWarnings("unchecked")
+ var customizer = ArgumentCaptor.forClass(BiFunction.class);
+ verify(autoConfiguration).addTracerProviderCustomizer(customizer.capture());
+
+ var pluginGenerator = new DeterministicIdGenerator();
+ pluginGenerator.setDurableExecutionArn("arn:spi");
+ pluginGenerator.setNextSpanOperationId("op-spi");
+
+ @SuppressWarnings("unchecked")
+ var tracerProviderCustomizer =
+ (BiFunction