aws-durable-execution-sdk-python-otel 0.3.0__tar.gz → 1.0.0__tar.gz

{aws_durable_execution_sdk_python_otel-0.3.0 → aws_durable_execution_sdk_python_otel-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: aws-durable-execution-sdk-python-otel
-Version: 0.3.0
+Version: 1.0.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
@@ -8,7 +8,7 @@ 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: Development Status :: 5 - Production/Stable
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -17,39 +17,70 @@ 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
+Requires-Dist: aws-durable-execution-sdk-python>=2.0.0
+Provides-Extra: standalone
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'standalone'
+Requires-Dist: opentelemetry-propagator-aws-xray; extra == 'standalone'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'standalone'
 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.
+OpenTelemetry instrumentation plugin for the [AWS Durable Execution SDK for Python](https://github.com/aws/aws-durable-execution-sdk-python). Emits durable execution spans on one execution trace, with deterministic workflow, synthetic-root, and operation span IDs.
 
 ## 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
+- **Shared Execution Trace**: Workflow and Invocation spans share one trace, anchored to a propagated backend parent when available or a deterministic synthetic execution root otherwise
+- **Same-Trace Ambient Parenting**: Invocation spans use the active ambient span only when it already belongs to the execution trace
 - **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
+- **Continuation Spans**: Operations completing in another invocation produce a new correlated span without fabricating an unobserved prior span context
 - **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
+- **Provider Integration**: Use the global ADOT provider or supply an explicit SDK `TracerProvider`
+- **Execution Sampling**: Resolve sampling once per invocation and apply it consistently to Workflow, Invocation, operation, and attempt spans
 
 ## Installation
 
+When using an ADOT or community OpenTelemetry Lambda layer:
+
 ```bash
 pip install aws-durable-execution-sdk-python-otel
 ```
 
+The base package intentionally does not install OpenTelemetry libraries. The
+Lambda layer supplies a version-aligned API, SDK, exporter, and propagators,
+preventing packages in the function artifact from shadowing parts of the layer.
+
+For an application that configures its own OpenTelemetry provider instead of
+using a Lambda layer:
+
+```bash
+pip install "aws-durable-execution-sdk-python-otel[standalone]"
+```
+
+The `standalone` extra installs the OpenTelemetry API, SDK, and AWS X-Ray
+propagator. The application remains responsible for configuring its provider,
+processors, and exporter.
+
 ## 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
+3. Pass `InvocationOtelPlugin` to your handler's `plugins` list
 4. Add X-Ray write permissions
 
+Alternatively, install this package in the function artifact or a Lambda layer
+and select either OTel plugin by entry-point name:
+
+```text
+DURABLE_EXECUTION_PLUGINS=otel-invocation
+DURABLE_EXECUTION_PLUGINS=otel-execution
+```
+
+`otel-invocation` creates `InvocationOtelPlugin`; `otel-execution` creates
+`ExecutionOtelPlugin`. The SDK discovers the selected package entry point at
+cold start, so the handler does not need to import or explicitly register the
+plugin.
+
 ### 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.
@@ -119,7 +150,7 @@ fn = lambda_.Function(
 
 ### 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.
+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 anchor the execution trace on the propagated X-Ray `Root`/`Parent` when both are valid, and preserves `Sampled=1` or `Sampled=0` as the backend sampling decision.
 
 **AWS Console:** Lambda → Configuration → Monitoring and operations tools → Active tracing → Enable
 
@@ -156,10 +187,10 @@ lambda_.Function(
 ```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
+from aws_durable_execution_sdk_python_otel import InvocationOtelPlugin
 
 
-@durable_execution(plugins=[OtelPlugin()])
+@durable_execution(plugins=[InvocationOtelPlugin()])
 def handler(event: dict, context: DurableContext) -> dict:
     result = context.step(lambda _: fetch_data(event["id"]), name="fetch-data")
 
@@ -170,7 +201,8 @@ def handler(event: dict, context: DurableContext) -> dict:
     return result
 ```
 
-That's it. The plugin handles TracerProvider setup, deterministic ID generation, and span lifecycle internally.
+The ADOT layer supplies the global `TracerProvider`; the plugin handles
+deterministic ID generation and span lifecycle.
 
 ### 4. Grant Permissions
 
@@ -185,7 +217,7 @@ The function's execution role needs the `AWSXRayDaemonWriteAccess` managed polic
 | `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.
+See the [ADOT sampling configuration](https://aws-otel.github.io/docs/getting-started/lambda#sampling-configuration) for more details. When the backend header contains an explicit `Sampled` value, that backend decision takes precedence over local sampler configuration for durable spans.
 
 ## Configuration
 
@@ -193,43 +225,104 @@ See the [ADOT sampling configuration](https://aws-otel.github.io/docs/getting-st
 
 ```python
 from aws_durable_execution_sdk_python_otel import (
-    OtelPlugin,
+    InvocationOtelPlugin,
+    OtelPluginConfig,
     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,
+plugin = InvocationOtelPlugin(
+    OtelPluginConfig(
+        # 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:
+Context extractors return an `ExtractedContext` object, or `None` when no
+durable execution trace context is available. The object carries:
+
+- `trace_id`: 128-bit OpenTelemetry trace ID
+- `parent_span_id`: 64-bit OpenTelemetry parent span ID
+- `sampling`: `Sampling.SAMPLED`, `Sampling.NOT_SAMPLED`, or `Sampling.UNDECIDED`
+
+The plugin supports multiple strategies for extracting durable execution trace
+context:
 
 ```python
 from aws_durable_execution_sdk_python_otel import (
-    OtelPlugin,
+    InvocationOtelPlugin,
+    OtelPluginConfig,
     w3c_client_context_extractor,
     xray_context_extractor,
 )
 
-# Default: X-Ray trace header (recommended for most Lambda deployments)
-OtelPlugin(context_extractor=xray_context_extractor)
+# Default: X-Ray trace header (recommended for most Lambda deployments).
+InvocationOtelPlugin(OtelPluginConfig(context_extractor=xray_context_extractor))
 
-# W3C Trace Context via clientContext (requires backend propagation support)
-OtelPlugin(context_extractor=w3c_client_context_extractor)
+# W3C Trace Context via clientContext (placeholder for backend propagation support).
+InvocationOtelPlugin(OtelPluginConfig(context_extractor=w3c_client_context_extractor))
 ```
 
+Custom extractors should return `ExtractedContext`, not an OpenTelemetry
+`Context`.
+
+### Trace Structure
+
+Both bundled plugins use the same execution ancestor:
+
+- a propagated backend parent when `_X_AMZN_TRACE_ID` contains a valid `Root`
+  and `Parent`
+- otherwise a deterministic, non-recording synthetic root derived from the
+  durable execution ARN
+
+`InvocationOtelPlugin` keeps durable operation spans under the Invocation span
+and links operations to Workflow:
+
+```text
+Execution ancestor
+├── Workflow
+└── Invocation
+    └── operation
+        └── operation attempt 1
+```
+
+`ExecutionOtelPlugin` keeps operation spans under Workflow and links operations
+to the current Invocation span:
+
+```text
+Execution ancestor
+├── Workflow
+│   └── operation
+│       └── operation attempt 1
+└── Invocation
+```
+
+If an ambient Lambda span is active and already has the execution trace ID, the
+Invocation span uses that ambient span as its parent. Ambient spans on a
+different trace are ignored for durable parenting so Invocation remains on the
+execution trace.
+
+### Sampling
+
+Sampling is resolved once per invocation and carried to every durable span in
+that invocation. Precedence is:
+
+1. `Sampled=1` or `Sampled=0` from `_X_AMZN_TRACE_ID`
+2. a same-trace ambient span's recording/sampled state
+3. the configured OpenTelemetry sampler
+
+The resolved decision is applied to Workflow, Invocation, operation, and attempt
+spans. This avoids independently querying stateful or ratio-based samplers for
+each durable span in the same invocation.
+
 ### Log Correlation
 
 When `enrich_logger=True` (the default), the plugin installs a logging filter on
@@ -249,8 +342,9 @@ 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
+2. **Check the CloudWatch console** — Navigate to CloudWatch → Traces in the AWS Console. You should see an execution trace with:
+   - A "Workflow" span exported on the terminal invocation
+   - 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
 
@@ -265,40 +359,60 @@ After deploying your function with the plugin configured:
 | 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         |
+| Traces appear but are fragmented  | Backend trace context is not propagated to every invocation     |
 | 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`
+### `InvocationOtelPlugin`
 
-The main plugin class. Implements `DurableInstrumentationPlugin` from `aws_durable_execution_sdk_python`.
+Invocation-rooted view. 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,
+InvocationOtelPlugin(
+    OtelPluginConfig(
+        tracer_provider=None,
+        context_extractor=None,
+        instrument_name="aws-durable-execution-sdk-python",
+        enrich_logger=True,
+        workflow_span_name="Workflow",
+    )
 )
 ```
 
+Pass `tracer_provider=...` when the application owns the OpenTelemetry SDK
+provider. When omitted, the globally configured provider is used.
+
+### `ExecutionOtelPlugin`
+
+Execution-rooted view. Uses the same execution ancestor and sampling behavior as
+`InvocationOtelPlugin`, but parents operation spans under Workflow and links
+them to Invocation.
+
 ### `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.
+Default context extractor. Reads the `_X_AMZN_TRACE_ID` environment variable and
+returns `ExtractedContext` containing parsed `Root`, `Parent`, and `Sampled`
+fields when present.
 
 ### `w3c_client_context_extractor`
 
-Alternative context extractor. Reads W3C `traceparent` from `context.clientContext.custom.traceparent`. Requires backend `clientContext` propagation to be enabled.
+Alternative context extractor placeholder. Returns `None` until backend W3C
+`traceparent` propagation is supported.
 
 ### `ContextExtractor`
 
-Type alias for custom context extractor functions.
+Type alias for custom context extractor functions:
+`Callable[[InvocationStartInfo], ExtractedContext | None]`.
+
+### `ExtractedContext` / `Sampling`
+
+Structured trace context and sampling decision returned by context extractors.
 
 ### `OtelContextLogFilter` / `install_log_filter`
 
@@ -309,9 +423,8 @@ setups.
 ## Requirements
 
 - Python >= 3.11
-- `aws-durable-execution-sdk-python` >= 1.5.0
-- `opentelemetry-api` >= 1.20.0
-- `opentelemetry-sdk` >= 1.20.0
+- `aws-durable-execution-sdk-python` >= 2.0.0
+- An ADOT/community OpenTelemetry Lambda layer, or the `standalone` extra
 
 ## License