aws-durable-execution-sdk-python-otel 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

aws_durable_execution_sdk_python_otel/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present Amazon.com, Inc. or its affiliates.
 #
 # SPDX-License-Identifier: Apache-2.0
-__version__ = "0.2.0"
+__version__ = "0.3.0"

aws_durable_execution_sdk_python_otel/__init__.py

@@ -14,7 +14,7 @@ from aws_durable_execution_sdk_python_otel.log_filter import (
     install_log_filter,
 )
 from aws_durable_execution_sdk_python_otel.plugin import (
-    DurableExecutionOtelPlugin,
+    OtelPlugin,
 )
 
 
@@ -22,8 +22,8 @@ __all__ = [
     "__version__",
     "ContextExtractor",
     "DeterministicIdGenerator",
-    "DurableExecutionOtelPlugin",
     "OtelContextLogFilter",
+    "OtelPlugin",
     "install_log_filter",
     "w3c_client_context_extractor",
     "xray_context_extractor",

aws_durable_execution_sdk_python_otel/deterministic_id_generator.py

@@ -66,9 +66,10 @@ def _to_otel_trace_id(execution_arn: str, start_timestamp: datetime | None) -> i
     return int(f"{time_part}{hash_part}", 16)
 
 
-def operation_id_to_span_id(operation_id: str) -> int:
-    """Derive a deterministic span ID (64 bits) from an operation ID."""
-    hashed_operation_id = hashlib.blake2b(operation_id.encode()).hexdigest()[:16]
+def operation_id_to_span_id(durable_execution_arn: str, operation_id: str) -> int:
+    """Derive a deterministic span ID (64 bits) from an execution and operation."""
+    plain_value = f"{durable_execution_arn}:{operation_id}"
+    hashed_operation_id = hashlib.blake2b(plain_value.encode()).hexdigest()[:16]
     return int(hashed_operation_id, 16)
 
 

aws_durable_execution_sdk_python_otel/log_filter.py

@@ -4,12 +4,11 @@ The filter attaches to a stdlib logging handler and enriches *every* record
 that flows through it: direct ``logging.getLogger().info(...)`` calls,
 child-logger records that propagate to root, and third-party library logs.
 
-The span/trace identifiers are added as ``LogRecord`` attributes (using
-underscore names, since dotted names are not valid record attributes):
+The span/trace identifiers are added as ``LogRecord`` attributes:
 
-    - ``otel_trace_id``: 32-char hex trace identifier
-    - ``otel_span_id``: 16-char hex span identifier
-    - ``otel_trace_sampled``: boolean indicating if the trace is sampled
+    - ``traceId``: 32-char hex trace identifier
+    - ``spanId``: 16-char hex span identifier
+    - ``otelTraceSampled``: boolean indicating if the trace is sampled
 
 These attributes are only set when a valid span context is active. Records
 emitted outside an active invocation (e.g. during Lambda teardown) pass through
@@ -25,7 +24,7 @@ from opentelemetry.trace import TraceFlags
 
 
 if TYPE_CHECKING:
-    from aws_durable_execution_sdk_python_otel.plugin import DurableExecutionOtelPlugin
+    from aws_durable_execution_sdk_python_otel.plugin import OtelPlugin
 
 
 class OtelContextLogFilter(logging.Filter):
@@ -45,7 +44,7 @@ class OtelContextLogFilter(logging.Filter):
         plugin: The OTel plugin instance that resolves the current span context.
     """
 
-    def __init__(self, plugin: DurableExecutionOtelPlugin) -> None:
+    def __init__(self, plugin: OtelPlugin) -> None:
         super().__init__()
         self._plugin = plugin
 
@@ -53,16 +52,16 @@ class OtelContextLogFilter(logging.Filter):
         """Stamp the active span context onto the record, then allow it through."""
         span_context = self._plugin.get_current_span_context()
         if span_context and span_context.is_valid:
-            record.otel_trace_id = format(span_context.trace_id, "032x")
-            record.otel_span_id = format(span_context.span_id, "016x")
-            record.otel_trace_sampled = bool(
+            record.traceId = format(span_context.trace_id, "032x")
+            record.spanId = format(span_context.span_id, "016x")
+            record.otelTraceSampled = bool(
                 span_context.trace_flags & TraceFlags.SAMPLED
             )
         return True
 
 
 def install_log_filter(
-    plugin: DurableExecutionOtelPlugin,
+    plugin: OtelPlugin,
     target_logger: logging.Logger | None = None,
 ) -> OtelContextLogFilter | None:
     """Attach an OtelContextLogFilter to a logger's handlers, idempotently.

aws_durable_execution_sdk_python_otel/plugin.py

@@ -21,7 +21,6 @@ from aws_durable_execution_sdk_python.plugin import (
 from opentelemetry import context, trace
 from opentelemetry.context import Context
 from opentelemetry.sdk.trace import TracerProvider as SdkTracerProvider
-from opentelemetry.sdk.trace.sampling import TraceIdRatioBased
 from opentelemetry.trace import (
     Link,
     Span,
@@ -52,7 +51,7 @@ def _to_otel_timestamp(dt: datetime.datetime | None) -> int | None:
     return int(dt.timestamp() * 1_000_000_000)
 
 
-class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
+class OtelPlugin(DurableInstrumentationPlugin):
     """OpenTelemetry instrumentation plugin for durable executions.
 
     The plugin creates spans for Lambda invocations, durable operations, and
@@ -68,9 +67,10 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
 
     Args:
         trace_provider: OpenTelemetry tracer provider used to create spans.
+            Optional; when omitted, the globally configured tracer provider
+            (``opentelemetry.trace.get_tracer_provider()``) is used.
         context_extractor: Optional extractor for upstream context. Defaults to
             AWS X-Ray header extraction.
-        sampling_rate: Ratio used by ``TraceIdRatioBased`` sampling.
         instrument_name: Instrumentation scope name registered with the tracer.
     """
 
@@ -78,17 +78,17 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
 
     def __init__(
         self,
-        trace_provider: SdkTracerProvider,
+        trace_provider: SdkTracerProvider | None = None,
         context_extractor: ContextExtractor | None = None,
-        sampling_rate: float = 1.0,
         instrument_name: str = DEFAULT_INSTRUMENT_NAME,
         enrich_logger: bool = True,
     ) -> None:
         """Initialize the plugin with an OpenTelemetry tracer provider.
 
-        The provided tracer provider is configured with this plugin's
-        deterministic ID generator and sampling strategy so spans for a durable
-        execution share stable trace and logical operation identifiers.
+        The tracer provider is configured with this plugin's deterministic ID
+        generator so spans for a durable execution share stable trace and
+        logical operation identifiers. When no provider is supplied, the
+        globally configured tracer provider is used.
 
         When enrich_logger is enabled (default), the plugin installs a logging
         filter on the root logger at invocation start that stamps the active
@@ -99,15 +99,28 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
             context_extractor or xray_context_extractor
         )
 
-        self._provider = trace_provider
-        # A ProxyTracerProvider (the API default from trace.get_tracer_provider()
-        # before an SDK provider is configured) has no id_generator; fall back to
-        # None so DeterministicIdGenerator uses its own default generator.
+        self._provider = trace_provider or trace.get_tracer_provider()
         self._id_generator: DeterministicIdGenerator = DeterministicIdGenerator(
             fallback_id_generator=getattr(self._provider, "id_generator", None)
         )
-        self._provider.id_generator = self._id_generator
-        self._provider.sampler = TraceIdRatioBased(sampling_rate)
+        # Deterministic trace stitching requires the SDK TracerProvider, which
+        # exposes id_generator/sampler. The API's default ProxyTracerProvider
+        # (returned before an SDK provider is configured) does not. Rather than
+        # fail the invocation over an observability concern, warn and continue:
+        # the proxy's tracer is effectively a no-op (and auto-delegates if an SDK
+        # provider is configured later). In a Lambda OTel/ADOT deployment the
+        # layer configures a real SDK provider before the handler imports.
+        if isinstance(self._provider, SdkTracerProvider):
+            self._provider.id_generator = self._id_generator
+        else:
+            logger.warning(
+                "OtelPlugin expected an SDK TracerProvider "
+                "(opentelemetry.sdk.trace.TracerProvider) but got %s. Spans will "
+                "not use deterministic IDs. "
+                "Ensure the OpenTelemetry SDK is configured (e.g. via the ADOT "
+                "Lambda layer) or pass an explicit trace_provider.",
+                type(self._provider).__name__,
+            )
         self._tracer: Tracer = self._provider.get_tracer(instrument_name)
 
         # per invocation status:
@@ -139,12 +152,18 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
         with self._operation_spans_lock:
             return self._operation_spans.get(operation_id)
 
+    @staticmethod
+    def _attempt_span_key(info: UserFunctionStartInfo | UserFunctionEndInfo) -> str:
+        """Return the registry key for a STEP attempt span."""
+        return f"{info.operation_id}:attempt:{info.attempt or 1}"
+
     def get_current_span_context(self) -> SpanContext | None:
         """Return the span context to use for log correlation.
 
         Resolution order:
-        1. The span attached to the OTel thread-local context. Inside a step or
-           child context this is the active operation span (attached in
+        1. The span attached to the OTel thread-local context. Inside a step
+           this is the active attempt span, and inside a child context this is
+           the active context span (attached in
            on_user_function_start), and between operations it is the enclosing
            operation span (restored in on_user_function_end).
         2. The invocation span from the plugin registry. This is the path used
@@ -196,6 +215,8 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
         start_time: datetime.datetime | None = None,
         parent_span: Span | None = None,
         existed: bool = False,
+        span_key: str | None = None,
+        deterministic_span_id: bool = True,
     ) -> Span:
         """Start and store a span for an invocation or durable operation.
 
@@ -210,6 +231,10 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
             existed: Whether the logical operation already had a previous span.
                 Continuation spans link back to the deterministic span ID for
                 the operation while using a fresh generated span ID.
+            span_key: Optional registry key. Defaults to ``operation_id``.
+            deterministic_span_id: Whether to use the deterministic operation
+                span ID. Attempt spans set this to ``False`` so they can be
+                separate children of the logical operation span.
 
         Returns:
             The started OpenTelemetry span.
@@ -220,11 +245,15 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
             name,
             parent_span,
         )
+        registry_key = span_key if span_key is not None else operation_id
         with self._operation_spans_lock:
-            if existed:
+            if not deterministic_span_id:
+                links = []
+                self._id_generator.set_next_span_id(None)
+            elif existed:
                 if not operation_id:
                     raise ValueError("operation id is required")
-                span_id = operation_id_to_span_id(operation_id)
+                span_id = operation_id_to_span_id(self._execution_arn, operation_id)
                 links = [
                     Link(
                         context=SpanContext(
@@ -240,7 +269,9 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
                 links = []
 
                 self._id_generator.set_next_span_id(
-                    operation_id_to_span_id(operation_id) if operation_id else None
+                    operation_id_to_span_id(self._execution_arn, operation_id)
+                    if operation_id
+                    else None
                 )
             if parent_span is None:
                 # root span
@@ -256,7 +287,7 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
                 context=parent_context,
                 links=links,
             )
-            self._operation_spans[operation_id] = span
+            self._operation_spans[registry_key] = span
 
         logger.debug("Started OTel span: %s", span)
         return span
@@ -324,8 +355,8 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
     def on_operation_start(self, info: OperationStartInfo) -> None:
         """Called when an operation begins. Creates a span for the operation."""
         logger.debug("Durable operation started: %s", info)
-        if info.operation_type in [OperationType.CONTEXT, OperationType.STEP]:
-            # Context and Step operations are tracked using on_user_function_start
+        if info.operation_type is OperationType.CONTEXT:
+            # Context operations are tracked using on_user_function_start.
             return
         parent_span = self._resolve_parent_span(info.parent_id)
         attributes = self._extract_attributes(info)
@@ -336,6 +367,7 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
             attributes=attributes,
             start_time=info.start_time,
             parent_span=parent_span,
+            existed=info.is_replayed,
         )
 
     def on_operation_end(self, info: OperationEndInfo) -> None:
@@ -348,8 +380,8 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
         operation span before being ended.
         """
         logger.debug("Durable operation ended: %s", info)
-        if info.operation_type in [OperationType.CONTEXT, OperationType.STEP]:
-            # Context and Step operations are tracked using on_user_function_end
+        if info.operation_type is OperationType.CONTEXT:
+            # Context operations are tracked using on_user_function_end.
             return
         span = self._get_span(info.operation_id)
         if not span:
@@ -365,6 +397,8 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
                 parent_span=parent_span,
                 existed=True,
             )
+        else:
+            span.set_attributes(self._extract_attributes(info))
 
         if info.error:
             span.set_status(StatusCode.ERROR, info.error.message or "")
@@ -384,8 +418,9 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
 
         This callback runs inside the thread that executes user code so the
         started span can be attached to the OpenTelemetry context for any
-        instrumentation used by that code. Attempts after the first are emitted
-        as continuation spans linked to the logical operation span.
+        instrumentation used by that code. STEP attempts are emitted as child
+        spans beneath the logical STEP operation span created by
+        ``on_operation_start``.
 
         Args:
             info: Information about the operation attempt.
@@ -396,15 +431,30 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
             raise RuntimeError(
                 "on_user_function_start should only be called for CONTEXT and STEP operations"
             )
-        parent_span = self._resolve_parent_span(info.parent_id)
+        if info.operation_type is OperationType.STEP:
+            parent_span = self._get_span(
+                info.operation_id
+            ) or self._resolve_parent_span(info.parent_id)
+        else:
+            parent_span = self._resolve_parent_span(info.parent_id)
         attributes = self._extract_attributes(info)
+        span_name = info.name or info.operation_id
+        if info.operation_type is OperationType.STEP:
+            span_name = f"{span_name} attempt {info.attempt or 1}"
+        span_key = (
+            self._attempt_span_key(info)
+            if info.operation_type is OperationType.STEP
+            else info.operation_id
+        )
         span = self._start_span(
             operation_id=info.operation_id,
-            name=info.name or info.operation_id,
+            name=span_name,
             attributes=attributes,
             start_time=info.start_time,
             parent_span=parent_span,
-            existed=info.attempt != 1,
+            existed=info.attempt != 1 and info.operation_type is not OperationType.STEP,
+            span_key=span_key,
+            deterministic_span_id=info.operation_type is not OperationType.STEP,
         )
         context.attach(trace.set_span_in_context(span, self._extracted_context))
 
@@ -424,7 +474,12 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
                 "on_user_function_end should only be called for CONTEXT and STEP operations"
             )
         # key = f"{info.operation_id}-{int(info.start_time.timestamp())}"
-        span = self._get_span(info.operation_id)
+        span_key = (
+            self._attempt_span_key(info)
+            if info.operation_type is OperationType.STEP
+            else info.operation_id
+        )
+        span = self._get_span(span_key)
         if not span:
             raise RuntimeError(
                 "on_user_function_end called without matching on_user_function_start"
@@ -440,16 +495,13 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
                     else "Unknown error"
                 )
             )
-        elif info.outcome is UserFunctionOutcome.SUCCEEDED:
-            span.set_status(StatusCode.OK)
         else:
-            # PENDING
-            span.set_status(StatusCode.UNSET, "PENDING")
+            span.set_status(StatusCode.OK)
 
         end_timestamp = info.end_time
         if end_timestamp is not None and end_timestamp == info.start_time:
             end_timestamp += datetime.timedelta(microseconds=1)
-        self._end_span(info.operation_id, end_timestamp)
+        self._end_span(span_key, end_timestamp)
         # Restore the enclosing operation span as current so code that runs
         # after this operation (e.g. between steps in a child context)
         # correlates to its enclosing operation, not the operation that just
@@ -478,11 +530,19 @@ class DurableExecutionOtelPlugin(DurableInstrumentationPlugin):
             attributes["durable.operation.id"] = info.operation_id
         if hasattr(info, "operation_type") and info.operation_type is not None:
             attributes["durable.operation.type"] = info.operation_type.value
+        if hasattr(info, "sub_type") and info.sub_type is not None:
+            attributes["durable.operation.subtype"] = info.sub_type.value
+        if hasattr(info, "status") and info.status is not None:
+            attributes["durable.operation.status"] = info.status.value
         if hasattr(info, "name") and info.name is not None:
             attributes["durable.operation.name"] = info.name
-        if hasattr(info, "attempt") and info.attempt is not None:
-            attributes["durable.attempt.number"] = info.attempt
-        if hasattr(info, "outcome") and info.outcome is not None:
-            attributes["durable.attempt.outcome"] = info.outcome.value
+        # Per-attempt fields are meaningful for STEP (each attempt is retried)
+        # but not for CONTEXT (a context is entered once per invocation, not
+        # retried). Omit them on CONTEXT spans for cross-SDK consistency.
+        if getattr(info, "operation_type", None) is not OperationType.CONTEXT:
+            if hasattr(info, "attempt") and info.attempt is not None:
+                attributes["durable.attempt.number"] = info.attempt
+            if hasattr(info, "outcome") and info.outcome is not None:
+                attributes["durable.attempt.outcome"] = info.outcome.value
 
         return attributes

aws_durable_execution_sdk_python_otel-0.3.0.dist-info/METADATA

@@ -0,0 +1,318 @@
+Metadata-Version: 2.4
+Name: aws-durable-execution-sdk-python-otel
+Version: 0.3.0
+Summary: OpenTelemetry instrumentation for AWS Durable Execution SDK for Python
+Project-URL: Documentation, https://github.com/aws/aws-durable-execution-sdk-python#readme
+Project-URL: Issues, https://github.com/aws/aws-durable-execution-sdk-python/issues
+Project-URL: Source, https://github.com/aws/aws-durable-execution-sdk-python
+Author-email: AWS durable-execution-dev <durable-execution-dev@amazon.com>
+License-Expression: Apache-2.0
+Keywords: durable-execution,observability,opentelemetry,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.11
+Requires-Dist: aws-durable-execution-sdk-python>=1.5.0
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-exporter-otlp
+Requires-Dist: opentelemetry-propagator-aws-xray
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Description-Content-Type: text/markdown
+
+# AWS Durable Execution SDK - OpenTelemetry Plugin
+
+OpenTelemetry instrumentation plugin for the [AWS Durable Execution SDK for Python](https://github.com/aws/aws-durable-execution-sdk-python). Emits distributed traces that correlate across multiple Lambda invocations of a single durable execution, producing deterministic span and trace IDs so that spans from different invocations are stitched into a single coherent trace.
+
+## Features
+
+- **Deterministic Trace IDs**: All invocations of the same durable execution share a single trace, derived from the X-Ray trace header or execution ARN
+- **Span-per-Operation**: Each durable operation (step, wait, invoke) gets its own span with accurate timing
+- **Continuation Spans**: Operations completing in a different invocation are linked back to the original span
+- **Log Correlation**: Enrich application logs with trace ID and span ID for end-to-end observability
+- **Configurable Sampling**: Control trace volume via plugin options
+- **Self-Contained Setup**: No manual TracerProvider configuration required
+
+## Installation
+
+```bash
+pip install aws-durable-execution-sdk-python-otel
+```
+
+## Quick Start using X-Ray/CloudWatch Tracing
+
+1. Add the [ADOT Lambda Layer](#1-adot-lambda-layer) to your function and set `AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument`
+2. Enable [X-Ray Active Tracing](#2-aws-x-ray-active-tracing) on the function
+3. Pass `OtelPlugin` to your handler's `plugins` list
+4. Add X-Ray write permissions
+
+### 1. ADOT Lambda Layer
+
+This plugin requires the [AWS Distro for OpenTelemetry (ADOT) Lambda layer](https://aws-otel.github.io/docs/getting-started/lambda) to export traces from your Lambda function.
+
+The layer ARN follows the format:
+
+```
+arn:aws:lambda:<region>:<awsAccountId>:layer:aws-otel-python-<arch>-ver-<version>
+```
+
+Refer to the [ADOT Lambda Layer ARNs](https://aws-otel.github.io/docs/getting-started/lambda/lambda-python) page for the latest version number, architecture, and supported regions.
+
+**AWS CLI:**
+
+```bash
+aws lambda update-function-configuration \
+  --function-name your-function-name \
+  --layers "arn:aws:lambda:<region>:<awsAccountId>:layer:aws-otel-python-amd64-ver-<version>"
+```
+
+You must also set the `AWS_LAMBDA_EXEC_WRAPPER` environment variable:
+
+```bash
+aws lambda update-function-configuration \
+  --function-name your-function-name \
+  --environment "Variables={AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument}"
+```
+
+> **Note:** Replace `<region>` with your function's region and `<version>`/`<arch>` with the latest layer version and architecture from the ADOT docs.
+
+**CloudFormation / SAM:**
+
+```yaml
+MyFunction:
+  Type: AWS::Serverless::Function
+  Properties:
+    Layers:
+      - !Sub arn:aws:lambda:${AWS::Region}:<awsAccountId>:layer:aws-otel-python-amd64-ver-<version>
+    Environment:
+      Variables:
+        AWS_LAMBDA_EXEC_WRAPPER: /opt/otel-instrument
+```
+
+**CDK:**
+
+```python
+from aws_cdk import aws_lambda as lambda_
+
+adot_layer = lambda_.LayerVersion.from_layer_version_arn(
+    self,
+    "AdotLayer",
+    f"arn:aws:lambda:<region>:<awsAccountId>:layer:aws-otel-python-amd64-ver-<version>",
+)
+
+fn = lambda_.Function(
+    self,
+    "MyFunction",
+    runtime=lambda_.Runtime.PYTHON_3_12,
+    handler="index.handler",
+    code=lambda_.Code.from_asset("lambda"),
+    layers=[adot_layer],
+    environment={"AWS_LAMBDA_EXEC_WRAPPER": "/opt/otel-instrument"},
+)
+```
+
+> **Tip:** Pin the layer version to a specific number in production deployments to avoid unexpected behavior from automatic version changes.
+
+### 2. AWS X-Ray Active Tracing
+
+Enable active tracing on your Lambda function so the `_X_AMZN_TRACE_ID` environment variable is populated at invocation time. The plugin uses this header to derive deterministic trace IDs that remain consistent across all invocations of the same durable execution.
+
+**AWS Console:** Lambda → Configuration → Monitoring and operations tools → Active tracing → Enable
+
+**AWS CLI:**
+
+```bash
+aws lambda update-function-configuration \
+  --function-name your-function-name \
+  --tracing-config Mode=Active
+```
+
+**CloudFormation / SAM:**
+
+```yaml
+MyFunction:
+  Type: AWS::Lambda::Function
+  Properties:
+    TracingConfig:
+      Mode: Active
+```
+
+**CDK:**
+
+```python
+lambda_.Function(
+    self,
+    "MyFunction",
+    tracing=lambda_.Tracing.ACTIVE,
+)
+```
+
+### 3. In your Lambda handler (index.py)
+
+```python
+from aws_durable_execution_sdk_python import DurableContext
+from aws_durable_execution_sdk_python.execution import durable_execution
+from aws_durable_execution_sdk_python_otel import OtelPlugin
+
+
+@durable_execution(plugins=[OtelPlugin()])
+def handler(event: dict, context: DurableContext) -> dict:
+    result = context.step(lambda _: fetch_data(event["id"]), name="fetch-data")
+
+    context.wait(duration=Duration.from_seconds(5))
+
+    context.step(lambda _: process(result), name="process")
+
+    return result
+```
+
+That's it. The plugin handles TracerProvider setup, deterministic ID generation, and span lifecycle internally.
+
+### 4. Grant Permissions
+
+The function's execution role needs the `AWSXRayDaemonWriteAccess` managed policy (or equivalent permissions) if using X-Ray as the tracing backend.
+
+### Environment Variables for ADOT layer
+
+| Variable                      | Description                                                                                   | Default           |
+| ----------------------------- | --------------------------------------------------------------------------------------------- | ----------------- |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint for the OTLP exporter (e.g., `http://localhost:4318` for the ADOT collector sidecar) | Set by ADOT layer |
+| `AWS_LAMBDA_EXEC_WRAPPER`     | Set to `/opt/otel-instrument` for the ADOT layer to instrument your function                  | —                 |
+| `OTEL_TRACES_SAMPLER`         | Sampler to use (e.g., `traceidratio` for ratio-based sampling)                                | `always_on`       |
+| `OTEL_TRACES_SAMPLER_ARG`     | Argument for the sampler (e.g., `0.3` to sample 30% of traces)                                | —                 |
+
+See the [ADOT sampling configuration](https://aws-otel.github.io/docs/getting-started/lambda#sampling-configuration) for more details.
+
+## Configuration
+
+### Plugin Options
+
+```python
+from aws_durable_execution_sdk_python_otel import (
+    OtelPlugin,
+    xray_context_extractor,
+)
+
+plugin = OtelPlugin(
+    # Provide your own TracerProvider if you already have one configured.
+    # Defaults to the globally configured tracer provider.
+    trace_provider=None,
+    # Use a custom context extractor (default: xray_context_extractor).
+    context_extractor=xray_context_extractor,
+    # Custom instrumentation scope name
+    # (default: "aws-durable-execution-sdk-python").
+    instrument_name="my-service",
+    # Install a root-logger filter that stamps trace context onto every
+    # log record (default: True).
+    enrich_logger=True,
+)
+```
+
+### Context Extractors
+
+The plugin supports multiple strategies for extracting upstream trace context:
+
+```python
+from aws_durable_execution_sdk_python_otel import (
+    OtelPlugin,
+    w3c_client_context_extractor,
+    xray_context_extractor,
+)
+
+# Default: X-Ray trace header (recommended for most Lambda deployments)
+OtelPlugin(context_extractor=xray_context_extractor)
+
+# W3C Trace Context via clientContext (requires backend propagation support)
+OtelPlugin(context_extractor=w3c_client_context_extractor)
+```
+
+### Log Correlation
+
+When `enrich_logger=True` (the default), the plugin installs a logging filter on
+the root logger at invocation start. The filter stamps the active OTel trace
+context onto every emitted log record using these attributes:
+
+- `traceId`: 32-char hex trace identifier
+- `spanId`: 16-char hex span identifier
+- `otelTraceSampled`: boolean indicating if the trace is sampled
+
+These attributes are only set when a valid span context is active, so any log
+formatter or schema must treat the fields as optional.
+
+## Verification
+
+After deploying your function with the plugin configured:
+
+1. **Invoke your durable function** — trigger at least one execution that includes multiple steps or a wait/resume cycle.
+
+2. **Check the CloudWatch console** — Navigate to CloudWatch → Traces in the AWS Console. You should see a trace with:
+   - An "invocation" span per invocation
+   - Child spans for each durable operation (named after your step names)
+   - All invocations of the same execution grouped under one trace ID
+
+3. **Check log correlation** — verify that your logs include `traceId` and `spanId` fields matching the spans in X-Ray.
+
+4. **Confirm sampling** — If you set `OTEL_TRACES_SAMPLER=traceidratio` and `OTEL_TRACES_SAMPLER_ARG` to a value less than 1.0, verify that only the expected proportion of traces appear.
+
+5. **Span links** — For operations that span multiple invocations (e.g., after a wait resumes), though span links are set, they are not visualized within the CloudWatch console.
+
+### Troubleshooting
+
+| Symptom                           | Likely Cause                                                    |
+| --------------------------------- | --------------------------------------------------------------- |
+| No traces appear                  | ADOT layer not configured, or `AWS_LAMBDA_EXEC_WRAPPER` not set |
+| Traces appear but are fragmented  | X-Ray active tracing not enabled on the Lambda function         |
+| Missing spans for some operations | `OTEL_TRACES_SAMPLER_ARG` set below 1.0                         |
+| `_X_AMZN_TRACE_ID` not populated  | X-Ray active tracing not enabled                                |
+
+## API Reference
+
+### `OtelPlugin`
+
+The main plugin class. Implements `DurableInstrumentationPlugin` from `aws_durable_execution_sdk_python`.
+
+```python
+OtelPlugin(
+    trace_provider=None,
+    context_extractor=None,
+    instrument_name="aws-durable-execution-sdk-python",
+    enrich_logger=True,
+)
+```
+
+### `DeterministicIdGenerator`
+
+A custom OpenTelemetry `IdGenerator` that produces reproducible trace and span IDs from execution metadata. Exported for advanced use cases.
+
+### `xray_context_extractor`
+
+Default context extractor. Reads the `_X_AMZN_TRACE_ID` environment variable to derive trace context.
+
+### `w3c_client_context_extractor`
+
+Alternative context extractor. Reads W3C `traceparent` from `context.clientContext.custom.traceparent`. Requires backend `clientContext` propagation to be enabled.
+
+### `ContextExtractor`
+
+Type alias for custom context extractor functions.
+
+### `OtelContextLogFilter` / `install_log_filter`
+
+The logging filter (and its installer) used to stamp trace context onto log
+records. Installed automatically when `enrich_logger=True`; exported for manual
+setups.
+
+## Requirements
+
+- Python >= 3.11
+- `aws-durable-execution-sdk-python` >= 1.5.0
+- `opentelemetry-api` >= 1.20.0
+- `opentelemetry-sdk` >= 1.20.0
+
+## License
+
+Apache-2.0

aws_durable_execution_sdk_python_otel-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+aws_durable_execution_sdk_python_otel/__about__.py,sha256=eMP6nYgoHQWcCgV4SvwAgcs8UrO25qIlEa33am5Bfpw,137
+aws_durable_execution_sdk_python_otel/__init__.py,sha256=8MbvOj7Bde-BHrZzvFqphYvGghUoXG5dN0hGhmSHMLw,844
+aws_durable_execution_sdk_python_otel/context_extractors.py,sha256=hI3ZeVsNZHYyw1eOgvDJv8Y5NQY2VDpzTr_VyNJMtPU,1332
+aws_durable_execution_sdk_python_otel/deterministic_id_generator.py,sha256=5lV3pyu0krZaoPwscOQG0lwV4caz5XXnPsa-FPFWQKs,5061
+aws_durable_execution_sdk_python_otel/log_filter.py,sha256=ypfbFWDbE35sxOzOZ32yIHbOIOR7ySMVymfsMfyr46U,4128
+aws_durable_execution_sdk_python_otel/plugin.py,sha256=VSyo160gyro4xv1sRM0JPiOYhSQPI2NYEUKz5zU5aQs,23926
+aws_durable_execution_sdk_python_otel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aws_durable_execution_sdk_python_otel/LICENSE,sha256=CeipvOyAZxBGUsFoaFqwkx54aPnIKEtm9a5u2uXxEws,10142
+aws_durable_execution_sdk_python_otel/NOTICE,sha256=1CkO1kwu3Q_OHYTj-d-yiBJA_lNN73a4zSntavaD4oc,67
+aws_durable_execution_sdk_python_otel-0.3.0.dist-info/METADATA,sha256=F8Pc8geychW3Pq2hFnRUM6ny07bptbjPnBXps8qgJiQ,12240
+aws_durable_execution_sdk_python_otel-0.3.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+aws_durable_execution_sdk_python_otel-0.3.0.dist-info/RECORD,,

{aws_durable_execution_sdk_python_otel-0.2.0.dist-info → aws_durable_execution_sdk_python_otel-0.3.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.30.1
+Generator: hatchling 1.31.0
 Root-Is-Purelib: true
 Tag: py3-none-any

aws_durable_execution_sdk_python_otel-0.2.0.dist-info/METADATA

@@ -1,67 +0,0 @@
-Metadata-Version: 2.4
-Name: aws-durable-execution-sdk-python-otel
-Version: 0.2.0
-Summary: OpenTelemetry instrumentation for AWS Durable Execution SDK for Python
-Project-URL: Documentation, https://github.com/aws/aws-durable-execution-sdk-python#readme
-Project-URL: Issues, https://github.com/aws/aws-durable-execution-sdk-python/issues
-Project-URL: Source, https://github.com/aws/aws-durable-execution-sdk-python
-Author-email: AWS durable-execution-dev <durable-execution-dev@amazon.com>
-License-Expression: Apache-2.0
-Keywords: durable-execution,observability,opentelemetry,tracing
-Classifier: Development Status :: 4 - Beta
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Programming Language :: Python :: Implementation :: CPython
-Classifier: Programming Language :: Python :: Implementation :: PyPy
-Requires-Python: >=3.11
-Requires-Dist: aws-durable-execution-sdk-python>=1.5.0
-Requires-Dist: opentelemetry-api>=1.20.0
-Requires-Dist: opentelemetry-exporter-otlp
-Requires-Dist: opentelemetry-propagator-aws-xray
-Requires-Dist: opentelemetry-sdk>=1.20.0
-Description-Content-Type: text/markdown
-
-# aws-durable-execution-sdk-python-otel
-
-OpenTelemetry instrumentation for the [AWS Durable Execution SDK for Python](https://github.com/aws/aws-durable-execution-sdk-python).
-
-> **Note:** v0.1.0 reserves the package name. Instrumentation lands in v0.2.0.
-
-## Overview
-
-This package will provide automatic OpenTelemetry tracing for durable execution workflows, giving you visibility into step execution, waits, retries, and overall workflow performance.
-
-## Installation
-
-```bash
-pip install aws-durable-execution-sdk-python-otel
-```
-
-## Quick Start
-
-```python
-from aws_durable_execution_sdk_python_otel import __version__
-
-print(__version__)
-```
-
-## Planned Features (v0.2.0)
-
-- Automatic span creation for steps, waits, invokes, and child contexts
-- Replay-aware tracing (distinguishes fresh executions from replays)
-- Error recording with proper OTel status codes
-- Configurable span attributes and naming
-
-## Requirements
-
-- Python >= 3.11
-- `aws-durable-execution-sdk-python` >= 1.5.0
-- `opentelemetry-api` >= 1.20.0
-- `opentelemetry-sdk` >= 1.20.0
-
-## License
-
-Apache-2.0

aws_durable_execution_sdk_python_otel-0.2.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-aws_durable_execution_sdk_python_otel/__about__.py,sha256=fN6OMpnwGW4dbezf3aG7wuWrAhfRPpRGifGrGbfb5QI,137
-aws_durable_execution_sdk_python_otel/__init__.py,sha256=3ssbxJTadtJWAv8TZVfWL0a6-d5kpmxj_pJCtpKT56w,876
-aws_durable_execution_sdk_python_otel/context_extractors.py,sha256=hI3ZeVsNZHYyw1eOgvDJv8Y5NQY2VDpzTr_VyNJMtPU,1332
-aws_durable_execution_sdk_python_otel/deterministic_id_generator.py,sha256=yVMJAvuzqOgFrw7vuHkUlrdAu53FtKtPf6jHLjK_AhQ,4963
-aws_durable_execution_sdk_python_otel/log_filter.py,sha256=FUDiNJ1cj4p-SRZ09YEZDpvZgWOA8BMw0MKTcoWAIrg,4281
-aws_durable_execution_sdk_python_otel/plugin.py,sha256=7OBNlpWmDxunvuXQvsMaHiKR-ZkofN0w1CUXxyWuXUE,20791
-aws_durable_execution_sdk_python_otel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-aws_durable_execution_sdk_python_otel/LICENSE,sha256=CeipvOyAZxBGUsFoaFqwkx54aPnIKEtm9a5u2uXxEws,10142
-aws_durable_execution_sdk_python_otel/NOTICE,sha256=1CkO1kwu3Q_OHYTj-d-yiBJA_lNN73a4zSntavaD4oc,67
-aws_durable_execution_sdk_python_otel-0.2.0.dist-info/METADATA,sha256=O1AdqEFUVG-gQbsBNbBvB-HjuqPwxVVnyYZOpTbWD3k,2386
-aws_durable_execution_sdk_python_otel-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-aws_durable_execution_sdk_python_otel-0.2.0.dist-info/RECORD,,