feat(otel): Add OpenTelemetry plugin module with deterministic tracing

examples/pom.xml

@@ -31,6 +31,25 @@
             <version>${project.version}</version>
         </dependency>
 
+        <!-- OTel Plugin -->
+        <dependency>
+            <groupId>software.amazon.lambda.durable</groupId>
+            <artifactId>aws-durable-execution-sdk-java-otel</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+
+        <!-- OpenTelemetry SDK (required for OTel example) -->
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-sdk</artifactId>
+            <version>1.62.0</version>
+        </dependency>
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-exporter-logging</artifactId>
+            <version>1.62.0</version>
+        </dependency>
+
         <!-- AWS Lambda Java Core -->
         <dependency>
             <groupId>com.amazonaws</groupId>

examples/src/main/java/software/amazon/lambda/durable/examples/general/OtelExample.java

@@ -0,0 +1,68 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.examples.general;
+
+import io.opentelemetry.exporter.logging.LoggingSpanExporter;
+import io.opentelemetry.sdk.trace.SdkTracerProvider;
+import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor;
+import software.amazon.lambda.durable.DurableConfig;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.examples.types.GreetingRequest;
+import software.amazon.lambda.durable.otel.DeterministicIdGenerator;
+import software.amazon.lambda.durable.otel.OpenTelemetryDurablePlugin;
+
+/**
+ * Example demonstrating OpenTelemetry instrumentation with the Durable Execution SDK.
+ *
+ * <p>This handler configures the OTel plugin with:
+ *
+ * <ul>
+ *   <li>Deterministic trace/span IDs (all invocations of the same execution share one trace)
+ *   <li>MDC log enrichment (trace_id and span_id in every log line)
+ *   <li>Logging exporter (spans printed to stdout → CloudWatch Logs)
+ * </ul>
+ *
+ * <p>In production, replace {@code LoggingSpanExporter} with {@code OtlpGrpcSpanExporter} to send spans to an OTLP
+ * collector (X-Ray, Datadog, etc.).
+ *
+ * <p>Expected trace structure:
+ *
+ * <pre>
+ * durable.invocation
+ * ├── durable.step:create-greeting [attempt 1]
+ * ├── durable.step:create-greeting (operation, backfilled)
+ * ├── durable.step:transform [attempt 1]
+ * └── durable.step:transform (operation, backfilled)
+ * </pre>
+ */
+public class OtelExample extends DurableHandler<GreetingRequest, String> {
+
+    @Override
+    protected DurableConfig createConfiguration() {
+        var idGenerator = new DeterministicIdGenerator();
+        var tracerProvider = SdkTracerProvider.builder()
+                .setIdGenerator(idGenerator)
+                .addSpanProcessor(SimpleSpanProcessor.create(LoggingSpanExporter.create()))
+                .build();
+        var otelPlugin = new OpenTelemetryDurablePlugin(tracerProvider, idGenerator);
+
+        return DurableConfig.builder().withPlugins(otelPlugin).build();
+    }
+
+    @Override
+    public String handleRequest(GreetingRequest input, DurableContext context) {
+        // Log with MDC — trace_id and span_id will be in the JSON output
+        context.getLogger().info("Starting OTel example for {}", input.getName());
+
+        var greeting = context.step("create-greeting", String.class, stepCtx -> {
+            context.getLogger().info("Inside step — this log has trace context in MDC");
+            return "Hello, " + input.getName();
+        });
+
+        var result = context.step("transform", String.class, stepCtx -> greeting.toUpperCase() + "!");
+
+        context.getLogger().info("OTel example complete: {}", result);
+        return result;
+    }
+}

examples/src/test/java/software/amazon/lambda/durable/examples/CloudBasedIntegrationTest.java

@@ -847,4 +847,17 @@ void testPluginExample() {
         assertNotNull(runner.getOperation("create-greeting"));
         assertNotNull(runner.getOperation("transform"));
     }
+
+    @Test
+    void testOtelExample() {
+        var runner =
+                CloudDurableTestRunner.create(arn("otel-example"), GreetingRequest.class, String.class, lambdaClient);
+        var result = runner.run(new GreetingRequest("World"));
+
+        assertEquals(ExecutionStatus.SUCCEEDED, result.getStatus());
+        assertEquals("HELLO, WORLD!", result.getResult());
+
+        assertNotNull(runner.getOperation("create-greeting"));
+        assertNotNull(runner.getOperation("transform"));
+    }
 }

examples/src/test/java/software/amazon/lambda/durable/examples/general/OtelExampleTest.java

@@ -0,0 +1,28 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.examples.general;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+import org.junit.jupiter.api.Test;
+import software.amazon.lambda.durable.examples.types.GreetingRequest;
+import software.amazon.lambda.durable.model.ExecutionStatus;
+import software.amazon.lambda.durable.testing.LocalDurableTestRunner;
+
+class OtelExampleTest {
+
+    @Test
+    void testOtelExample_executesSuccessfully() {
+        var handler = new OtelExample();
+        var runner = LocalDurableTestRunner.create(GreetingRequest.class, handler);
+
+        var result = runner.run(new GreetingRequest("World"));
+
+        assertEquals(ExecutionStatus.SUCCEEDED, result.getStatus());
+        assertEquals("HELLO, WORLD!", result.getResult(String.class));
+
+        assertNotNull(result.getOperation("create-greeting"));
+        assertNotNull(result.getOperation("transform"));
+    }
+}

examples/template.yaml

@@ -344,6 +344,17 @@ Resources:
       Handler: "software.amazon.lambda.durable.examples.general.PluginExample"
       Role: !Ref RoleArn
 
+  OtelExampleFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      FunctionName: !Join
+        - '-'
+        - - 'otel-example'
+          - !Ref JavaVersion
+          - runtime
+      Handler: "software.amazon.lambda.durable.examples.general.OtelExample"
+      Role: !Ref RoleArn
+
   RetryInvokeExampleFunction:
     Type: AWS::Serverless::Function
     Properties:
@@ -546,6 +557,10 @@ Outputs:
     Description: Plugin Example Function ARN
     Value: !GetAtt PluginExampleFunction.Arn
 
+  OtelExampleFunction:
+    Description: OTel Example Function ARN
+    Value: !GetAtt OtelExampleFunction.Arn
+
   RetryInvokeExampleFunction:
     Description: Retry Invoke Example Function ARN
     Value: !GetAtt RetryInvokeExampleFunction.Arn

otel-plugin/pom.xml

@@ -0,0 +1,105 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>software.amazon.lambda.durable</groupId>
+        <artifactId>aws-durable-execution-sdk-java-parent</artifactId>
+        <version>1.1.1-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>aws-durable-execution-sdk-java-otel</artifactId>
+    <name>AWS Lambda Durable Execution SDK - OpenTelemetry Plugin</name>
+    <description>OpenTelemetry instrumentation plugin for AWS Lambda Durable Execution SDK</description>
+
+    <properties>
+        <opentelemetry.version>1.62.0</opentelemetry.version>
+    </properties>
+
+    <dependencies>
+        <!-- Durable Execution SDK (for plugin interface) -->
+        <dependency>
+            <groupId>software.amazon.lambda.durable</groupId>
+            <artifactId>aws-durable-execution-sdk-java</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+
+        <!-- OpenTelemetry API (compile dependency — users bring the SDK implementation) -->
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-api</artifactId>
+            <version>${opentelemetry.version}</version>
+        </dependency>
+
+        <!-- OpenTelemetry SDK (provided — users bring their own SDK configuration) -->
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-sdk</artifactId>
+            <version>${opentelemetry.version}</version>
+            <scope>provided</scope>
+        </dependency>
+
+        <!-- OpenTelemetry Context (transitive from API, but explicit for clarity) -->
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-context</artifactId>
+            <version>${opentelemetry.version}</version>
+        </dependency>
+
+        <!-- AWS X-Ray Propagator (official OTel contrib) -->
+        <dependency>
+            <groupId>io.opentelemetry.contrib</groupId>
+            <artifactId>opentelemetry-aws-xray-propagator</artifactId>
+            <version>1.56.0-alpha</version>
+        </dependency>
+
+        <!-- SLF4J for logging -->
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+        </dependency>
+
+        <!-- Test dependencies -->
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-sdk-testing</artifactId>
+            <version>${opentelemetry.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>ch.qos.logback</groupId>
+            <artifactId>logback-classic</artifactId>
+            <version>1.5.18</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>com.diffplug.spotless</groupId>
+                <artifactId>spotless-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+</project>

otel-plugin/src/main/java/software/amazon/lambda/durable/otel/ContextExtractor.java

@@ -0,0 +1,27 @@
+// 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.context.Context;
+
+/**
+ * Extracts OTel trace context from the Lambda runtime environment.
+ *
+ * <p>Implementations read trace context from various sources (X-Ray trace header, W3C traceparent, etc.) and return an
+ * OTel {@link Context} that can be used as the parent for invocation spans.
+ *
+ * <p>Called once per invocation in {@code onInvocationStart} to establish the parent trace context.
+ *
+ * @deprecated This is a preview API that is experimental and may be changed or removed in future releases.
+ */
+@Deprecated
+@FunctionalInterface
+public interface ContextExtractor {
+
+    /**
+     * Extracts trace context from the runtime environment.
+     *
+     * @return the extracted OTel context, or {@link Context#root()} if no context is available
+     */
+    Context extract();
+}