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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: aws-durable-execution-sdk-python-otel
-Version: 1.0.0
+Version: 1.1.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
@@ -17,7 +17,7 @@ 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>=2.0.0
+Requires-Dist: aws-durable-execution-sdk-python>=2.1.0
 Provides-Extra: standalone
 Requires-Dist: opentelemetry-api>=1.20.0; extra == 'standalone'
 Requires-Dist: opentelemetry-propagator-aws-xray; extra == 'standalone'
@@ -50,6 +50,12 @@ 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.
 
+The generated `aws-durable-execution-sdk-python-otel-plugin` Lambda layer includes
+Core's runtime dependencies, including its required boto3/botocore service model.
+It still leaves OpenTelemetry provider packages to the ADOT/community layer.
+Dependencies bundled in the function artifact take precedence over layer packages;
+those application-owned boto3/botocore versions must also meet Core's minimum.
+
 For an application that configures its own OpenTelemetry provider instead of
 using a Lambda layer:
 
@@ -81,6 +87,32 @@ DURABLE_EXECUTION_PLUGINS=otel-execution
 cold start, so the handler does not need to import or explicitly register the
 plugin.
 
+OTel 1.1.0 requires core SDK 2.1.0 or later for the invocation-worker lifecycle
+and automatic mutual-exclusion validation. Publish the redesigned core first,
+then the plugin. Core 2.0.x runs invocation hooks on the caller and cannot provide
+the new plugin's handler propagation and host-context isolation; that version
+pair is not supported by OTel 1.1.0.
+Configure only one OTel view on every core version. `InvocationOtelPlugin`
+shows work within each Lambda invocation; `ExecutionOtelPlugin` shows logical
+operations across the whole execution. They emit overlapping telemetry and
+manage competing active contexts, so the coordinated core 2.1+/OTel 1.1+ pair
+rejects both at cold start with `PluginLoadError` naming both views. Keep only one across the combined
+`plugins=[...]` and `DURABLE_EXECUTION_PLUGINS` configuration. Unrelated plugins
+may run alongside the selected view; using no OTel plugin is also supported.
+
+The bundled views explicitly declare `__durable_registration_api__ = 1`.
+Custom subclasses inherit their group validation and registration cleanup.
+The closest marker gates registration and selects the callback contract; an
+explicit value other than the integer `1` shadows the inherited opt-in.
+Once enabled, each MRO class explicitly declaring the integer `1` contributes
+its resolved `exclusive_group`. A subclass's own group adds to the inherited
+view group rather than replacing it; `None` cannot remove an inherited group.
+Repeated groups count once per plugin. Unmarked classes' unrelated fields/helpers
+named `exclusive_group` or `on_registration_result` remain inert. Repeat the marker
+to add a group or customize the callback, which is still notified once per plugin.
+Re-accepting a previously rejected bundled instance
+restores its constructor-time logger enrichment immediately.
+
 ### 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.
@@ -182,6 +214,38 @@ lambda_.Function(
 )
 ```
 
+### Handler context propagation
+
+The core runs the existing Start hooks, handler, output preparation, resource
+cleanup and End hooks on one invocation worker. Start finishes before checkpoint
+processing begins. End follows registered-branch joins and checkpoint shutdown,
+and output serialization or checkpoint errors retain their normal classification.
+There is no separate handler-context plugin API.
+
+During Start, Invocation view preserves a valid active span on the canonical
+execution trace; when it is absent or unrelated, it attaches the Invocation span.
+Execution view attaches the Workflow span, including when an incoming span is on
+the same trace. The Invocation span's own ambient parenting is separate from the
+active context supplied to handler instrumentation. Both views preserve baggage.
+
+Start hooks run in registration order. A later successful plugin that deliberately
+sets or clears the active span wins; OTel does not apply a second correction pass.
+Place OTel after a span-replacing plugin when OTel's view-specific context is
+desired. Baggage-only plugins that extend the current context can appear on either
+side. The SDK also copies the coordinator's current bindings for each `map` or
+`parallel` branch admission/resume when plugins are registered. Baggage and
+other successful bindings reach these SDK-managed callbacks, while a branch's
+changes cannot leak into siblings, the coordinator or a reused worker.
+End hooks also retain registration order and reset tokens in their owning
+Context; they do not promise a reverse-stack observation of other plugins' spans.
+Existing registration, factory lifetime and checkpoint formats are unchanged.
+
+Upgrade both core to 2.1+ and OTel to 1.1+ for these guarantees. The released
+OTel 1.0 plugin can run on the new core with worker/host isolation, but its
+Invocation view does not attach the new fallback; a core-only upgrade does not
+supply that plugin behavior. CI tests the new pair as installed wheels and tests
+the actual released plugin separately, including before core 2.1 is on PyPI.
+
 ### 3. In your Lambda handler (index.py)
 
 ```python
@@ -280,8 +344,8 @@ 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
+- otherwise a deterministic `DurableExecutionRoot` span derived from the
+  durable execution ARN, with `durable.execution.synthetic_root=true`
 
 `InvocationOtelPlugin` keeps durable operation spans under the Invocation span
 and links operations to Workflow:
@@ -310,10 +374,46 @@ 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.
 
+### Synthetic fallback anchor
+
+Each sampled fallback invocation creates and ends `DurableExecutionRoot` at
+invocation start and attempts to flush it through the normal invocation-end
+lifecycle, including when it returns `PENDING` or `RETRY`. A successfully
+delivered copy supplies ancestry if the execution is later stopped or times out
+without resuming. Export and flush failures, or termination before flushing,
+do not provide a delivery guarantee.
+
+The anchor uses the existing execution-scoped span ID and the stable execution
+start timestamp for both its start and end. It carries no terminal outcome;
+`Workflow` remains the span for execution duration and success/failure. Retries
+of the first invocation and later invocations may re-export the same anchor to
+recover lost telemetry; export is not exactly once. Two executions sharing a
+propagated trace ID retain distinct ARN-scoped anchor IDs.
+The anchor is intentionally zero-duration, so its descendants end after it;
+trace viewers may flag that timing relationship even though the ancestry is valid.
+
+The anchor uses the same configured tracer, provider resource and processors as
+other durable spans, but carries only the resolved sampling decision. Its SDK
+attributes are `durable.execution.arn` and `durable.execution.synthetic_root`;
+sampler-added attributes and tracestate are omitted from this repeated identity.
+Ordinary durable spans retain the complete resolved sampler metadata. SDK-added
+IDs, timestamps and anchor attributes stay stable across recovery exports;
+provider resources and custom processor enrichment may vary. The SDK does not
+replace configured service identity or freeze detector fields.
+
+Complete remote parents are externally owned and are never materialized by the
+SDK. Unsampled invocations emit no anchor. Sampling remains resolved per
+invocation: a later sampled fallback invocation also emits the anchor even if
+an earlier invocation was unsampled. Missing execution start time continues to
+disable telemetry; no wall-clock timestamp is invented for the anchor.
+
 ### Sampling
 
 Sampling is resolved once per invocation and carried to every durable span in
-that invocation. Precedence is:
+that invocation. Each span consumes its private sampling intent before processors
+run. Processor-created spans use their own configured sampling policy and normal
+parent-context semantics, including when a processor forwards the supplied parent
+context. Precedence is:
 
 1. `Sampled=1` or `Sampled=0` from `_X_AMZN_TRACE_ID`
 2. a same-trace ambient span's recording/sampled state
@@ -323,6 +423,26 @@ 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.
 
+### Status attributes
+
+`durable.invocation.status` uses `RETRYING` when the core plugin hook reports
+`InvocationStatus.RETRY`. The core enum remains unchanged. Operation spans use
+OTel `OK` only for `SUCCEEDED`, `ERROR` when error details are delivered, and
+`UNSET` for other outcomes without error details, including `FAILED`,
+`CANCELLED`, `TIMED_OUT`, and `STOPPED`. The original durable operation status
+remains in `durable.operation.status`.
+
+### Invocation context isolation
+
+With core 2.1+, invocation hooks and the handler run on one worker in an
+invocation-local Context initialized from the host's bindings. Successful Start
+bindings are visible to later hooks, the handler and resource cleanup. The host's
+bindings remain unchanged after return, even if a plugin fails during Start or
+End. A failed Start's bindings are discarded for subsequent work, while End runs
+in that Start's original Context to preserve token ownership. This isolates
+context-variable bindings; it does not undo mutations to shared objects or
+external side effects. The isolation applies when plugins are registered.
+
 ### Log Correlation
 
 When `enrich_logger=True` (the default), the plugin installs a logging filter on
@@ -336,6 +456,40 @@ context onto every emitted log record using these attributes:
 These attributes are only set when a valid span context is active, so any log
 formatter or schema must treat the fields as optional.
 
+## Chained-invoke propagation
+
+Both views supply the synchronous `provide_propagation_metadata` hook with
+SDK-owned types. It encodes canonical X-Ray `Root`, the calling operation's
+`Parent`, and resolved `Sampled=1` or `Sampled=0`, without creating an extra span.
+An existing operation's actual span ID is used; before span creation, its stable
+ID is derived from the execution ARN and operation ID. Unrelated ambient spans
+cannot replace execution ownership. An operation that has already started uses
+its actual span's sampled flag. A deferred operation contributes metadata only
+while the instrumentation tracer still uses the installed `DurableSampler`:
+replacing that sampler after invocation Start may give the operation a different
+sampling decision, so the producer abstains instead of guessing or querying the
+sampler early. Inactive/mismatched executions contribute nothing. Tracer,
+provider and resource ownership remain unchanged.
+
+The core now calls the collector only for a new invoke START and persists the
+contribution in flat `ChainedInvokeOptions.XAmznTraceId`. Pending and terminal
+replay do not recollect metadata; an uncommitted START can be retried. Separate
+invokes carry separate operation parents. Public invoke tests cover both views,
+sampled/unsampled context, parallel branches, preserved tenant/payload and replay.
+
+For [#751](https://github.com/aws/aws-durable-execution-sdk-python/issues/751),
+deployed backend delivery and topology still require validation. The core requires
+boto3 1.43.114 or newer, which depends on a botocore model containing the optional
+field. The normal request tests use the published serializer and parameter
+validation. Python has no distributed-map
+model/START path; existing map/parallel APIs are CONTEXT operations.
+
+On older supported cores without the propagation contract, plugin loading and
+existing tracing continue, and the optional hook contributes no metadata. The
+new capability requires the coordinated core and its boto3 minimum. The core/OTel
+package floor and provider API version are unchanged; the published model alone
+does not establish deployed downstream topology.
+
 ## Verification
 
 After deploying your function with the plugin configured:
@@ -394,6 +548,11 @@ them to Invocation.
 
 A custom OpenTelemetry `IdGenerator` that produces reproducible trace and span IDs from execution metadata. Exported for advanced use cases.
 
+`use_ids` retains its existing scope-wide trace override by default. The
+synthetic-root implementation uses a separate internal one-span override,
+preventing processor-created roots from inheriting that internal ID. Existing
+`use_ids` signatures and default behavior remain unchanged.
+
 ### `xray_context_extractor`
 
 Default context extractor. Reads the `_X_AMZN_TRACE_ID` environment variable and
@@ -423,7 +582,7 @@ setups.
 ## Requirements
 
 - Python >= 3.11
-- `aws-durable-execution-sdk-python` >= 2.0.0
+- `aws-durable-execution-sdk-python` >= 2.1.0 (release the redesigned core before OTel 1.1.0)
 - An ADOT/community OpenTelemetry Lambda layer, or the `standalone` extra
 
 ## License

{aws_durable_execution_sdk_python_otel-1.0.0 → aws_durable_execution_sdk_python_otel-1.1.0}/README.md

@@ -24,6 +24,12 @@ 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.
 
+The generated `aws-durable-execution-sdk-python-otel-plugin` Lambda layer includes
+Core's runtime dependencies, including its required boto3/botocore service model.
+It still leaves OpenTelemetry provider packages to the ADOT/community layer.
+Dependencies bundled in the function artifact take precedence over layer packages;
+those application-owned boto3/botocore versions must also meet Core's minimum.
+
 For an application that configures its own OpenTelemetry provider instead of
 using a Lambda layer:
 
@@ -55,6 +61,32 @@ DURABLE_EXECUTION_PLUGINS=otel-execution
 cold start, so the handler does not need to import or explicitly register the
 plugin.
 
+OTel 1.1.0 requires core SDK 2.1.0 or later for the invocation-worker lifecycle
+and automatic mutual-exclusion validation. Publish the redesigned core first,
+then the plugin. Core 2.0.x runs invocation hooks on the caller and cannot provide
+the new plugin's handler propagation and host-context isolation; that version
+pair is not supported by OTel 1.1.0.
+Configure only one OTel view on every core version. `InvocationOtelPlugin`
+shows work within each Lambda invocation; `ExecutionOtelPlugin` shows logical
+operations across the whole execution. They emit overlapping telemetry and
+manage competing active contexts, so the coordinated core 2.1+/OTel 1.1+ pair
+rejects both at cold start with `PluginLoadError` naming both views. Keep only one across the combined
+`plugins=[...]` and `DURABLE_EXECUTION_PLUGINS` configuration. Unrelated plugins
+may run alongside the selected view; using no OTel plugin is also supported.
+
+The bundled views explicitly declare `__durable_registration_api__ = 1`.
+Custom subclasses inherit their group validation and registration cleanup.
+The closest marker gates registration and selects the callback contract; an
+explicit value other than the integer `1` shadows the inherited opt-in.
+Once enabled, each MRO class explicitly declaring the integer `1` contributes
+its resolved `exclusive_group`. A subclass's own group adds to the inherited
+view group rather than replacing it; `None` cannot remove an inherited group.
+Repeated groups count once per plugin. Unmarked classes' unrelated fields/helpers
+named `exclusive_group` or `on_registration_result` remain inert. Repeat the marker
+to add a group or customize the callback, which is still notified once per plugin.
+Re-accepting a previously rejected bundled instance
+restores its constructor-time logger enrichment immediately.
+
 ### 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.
@@ -156,6 +188,38 @@ lambda_.Function(
 )
 ```
 
+### Handler context propagation
+
+The core runs the existing Start hooks, handler, output preparation, resource
+cleanup and End hooks on one invocation worker. Start finishes before checkpoint
+processing begins. End follows registered-branch joins and checkpoint shutdown,
+and output serialization or checkpoint errors retain their normal classification.
+There is no separate handler-context plugin API.
+
+During Start, Invocation view preserves a valid active span on the canonical
+execution trace; when it is absent or unrelated, it attaches the Invocation span.
+Execution view attaches the Workflow span, including when an incoming span is on
+the same trace. The Invocation span's own ambient parenting is separate from the
+active context supplied to handler instrumentation. Both views preserve baggage.
+
+Start hooks run in registration order. A later successful plugin that deliberately
+sets or clears the active span wins; OTel does not apply a second correction pass.
+Place OTel after a span-replacing plugin when OTel's view-specific context is
+desired. Baggage-only plugins that extend the current context can appear on either
+side. The SDK also copies the coordinator's current bindings for each `map` or
+`parallel` branch admission/resume when plugins are registered. Baggage and
+other successful bindings reach these SDK-managed callbacks, while a branch's
+changes cannot leak into siblings, the coordinator or a reused worker.
+End hooks also retain registration order and reset tokens in their owning
+Context; they do not promise a reverse-stack observation of other plugins' spans.
+Existing registration, factory lifetime and checkpoint formats are unchanged.
+
+Upgrade both core to 2.1+ and OTel to 1.1+ for these guarantees. The released
+OTel 1.0 plugin can run on the new core with worker/host isolation, but its
+Invocation view does not attach the new fallback; a core-only upgrade does not
+supply that plugin behavior. CI tests the new pair as installed wheels and tests
+the actual released plugin separately, including before core 2.1 is on PyPI.
+
 ### 3. In your Lambda handler (index.py)
 
 ```python
@@ -254,8 +318,8 @@ 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
+- otherwise a deterministic `DurableExecutionRoot` span derived from the
+  durable execution ARN, with `durable.execution.synthetic_root=true`
 
 `InvocationOtelPlugin` keeps durable operation spans under the Invocation span
 and links operations to Workflow:
@@ -284,10 +348,46 @@ 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.
 
+### Synthetic fallback anchor
+
+Each sampled fallback invocation creates and ends `DurableExecutionRoot` at
+invocation start and attempts to flush it through the normal invocation-end
+lifecycle, including when it returns `PENDING` or `RETRY`. A successfully
+delivered copy supplies ancestry if the execution is later stopped or times out
+without resuming. Export and flush failures, or termination before flushing,
+do not provide a delivery guarantee.
+
+The anchor uses the existing execution-scoped span ID and the stable execution
+start timestamp for both its start and end. It carries no terminal outcome;
+`Workflow` remains the span for execution duration and success/failure. Retries
+of the first invocation and later invocations may re-export the same anchor to
+recover lost telemetry; export is not exactly once. Two executions sharing a
+propagated trace ID retain distinct ARN-scoped anchor IDs.
+The anchor is intentionally zero-duration, so its descendants end after it;
+trace viewers may flag that timing relationship even though the ancestry is valid.
+
+The anchor uses the same configured tracer, provider resource and processors as
+other durable spans, but carries only the resolved sampling decision. Its SDK
+attributes are `durable.execution.arn` and `durable.execution.synthetic_root`;
+sampler-added attributes and tracestate are omitted from this repeated identity.
+Ordinary durable spans retain the complete resolved sampler metadata. SDK-added
+IDs, timestamps and anchor attributes stay stable across recovery exports;
+provider resources and custom processor enrichment may vary. The SDK does not
+replace configured service identity or freeze detector fields.
+
+Complete remote parents are externally owned and are never materialized by the
+SDK. Unsampled invocations emit no anchor. Sampling remains resolved per
+invocation: a later sampled fallback invocation also emits the anchor even if
+an earlier invocation was unsampled. Missing execution start time continues to
+disable telemetry; no wall-clock timestamp is invented for the anchor.
+
 ### Sampling
 
 Sampling is resolved once per invocation and carried to every durable span in
-that invocation. Precedence is:
+that invocation. Each span consumes its private sampling intent before processors
+run. Processor-created spans use their own configured sampling policy and normal
+parent-context semantics, including when a processor forwards the supplied parent
+context. Precedence is:
 
 1. `Sampled=1` or `Sampled=0` from `_X_AMZN_TRACE_ID`
 2. a same-trace ambient span's recording/sampled state
@@ -297,6 +397,26 @@ 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.
 
+### Status attributes
+
+`durable.invocation.status` uses `RETRYING` when the core plugin hook reports
+`InvocationStatus.RETRY`. The core enum remains unchanged. Operation spans use
+OTel `OK` only for `SUCCEEDED`, `ERROR` when error details are delivered, and
+`UNSET` for other outcomes without error details, including `FAILED`,
+`CANCELLED`, `TIMED_OUT`, and `STOPPED`. The original durable operation status
+remains in `durable.operation.status`.
+
+### Invocation context isolation
+
+With core 2.1+, invocation hooks and the handler run on one worker in an
+invocation-local Context initialized from the host's bindings. Successful Start
+bindings are visible to later hooks, the handler and resource cleanup. The host's
+bindings remain unchanged after return, even if a plugin fails during Start or
+End. A failed Start's bindings are discarded for subsequent work, while End runs
+in that Start's original Context to preserve token ownership. This isolates
+context-variable bindings; it does not undo mutations to shared objects or
+external side effects. The isolation applies when plugins are registered.
+
 ### Log Correlation
 
 When `enrich_logger=True` (the default), the plugin installs a logging filter on
@@ -310,6 +430,40 @@ context onto every emitted log record using these attributes:
 These attributes are only set when a valid span context is active, so any log
 formatter or schema must treat the fields as optional.
 
+## Chained-invoke propagation
+
+Both views supply the synchronous `provide_propagation_metadata` hook with
+SDK-owned types. It encodes canonical X-Ray `Root`, the calling operation's
+`Parent`, and resolved `Sampled=1` or `Sampled=0`, without creating an extra span.
+An existing operation's actual span ID is used; before span creation, its stable
+ID is derived from the execution ARN and operation ID. Unrelated ambient spans
+cannot replace execution ownership. An operation that has already started uses
+its actual span's sampled flag. A deferred operation contributes metadata only
+while the instrumentation tracer still uses the installed `DurableSampler`:
+replacing that sampler after invocation Start may give the operation a different
+sampling decision, so the producer abstains instead of guessing or querying the
+sampler early. Inactive/mismatched executions contribute nothing. Tracer,
+provider and resource ownership remain unchanged.
+
+The core now calls the collector only for a new invoke START and persists the
+contribution in flat `ChainedInvokeOptions.XAmznTraceId`. Pending and terminal
+replay do not recollect metadata; an uncommitted START can be retried. Separate
+invokes carry separate operation parents. Public invoke tests cover both views,
+sampled/unsampled context, parallel branches, preserved tenant/payload and replay.
+
+For [#751](https://github.com/aws/aws-durable-execution-sdk-python/issues/751),
+deployed backend delivery and topology still require validation. The core requires
+boto3 1.43.114 or newer, which depends on a botocore model containing the optional
+field. The normal request tests use the published serializer and parameter
+validation. Python has no distributed-map
+model/START path; existing map/parallel APIs are CONTEXT operations.
+
+On older supported cores without the propagation contract, plugin loading and
+existing tracing continue, and the optional hook contributes no metadata. The
+new capability requires the coordinated core and its boto3 minimum. The core/OTel
+package floor and provider API version are unchanged; the published model alone
+does not establish deployed downstream topology.
+
 ## Verification
 
 After deploying your function with the plugin configured:
@@ -368,6 +522,11 @@ them to Invocation.
 
 A custom OpenTelemetry `IdGenerator` that produces reproducible trace and span IDs from execution metadata. Exported for advanced use cases.
 
+`use_ids` retains its existing scope-wide trace override by default. The
+synthetic-root implementation uses a separate internal one-span override,
+preventing processor-created roots from inheriting that internal ID. Existing
+`use_ids` signatures and default behavior remain unchanged.
+
 ### `xray_context_extractor`
 
 Default context extractor. Reads the `_X_AMZN_TRACE_ID` environment variable and
@@ -397,7 +556,7 @@ setups.
 ## Requirements
 
 - Python >= 3.11
-- `aws-durable-execution-sdk-python` >= 2.0.0
+- `aws-durable-execution-sdk-python` >= 2.1.0 (release the redesigned core before OTel 1.1.0)
 - An ADOT/community OpenTelemetry Lambda layer, or the `standalone` extra
 
 ## License

{aws_durable_execution_sdk_python_otel-1.0.0 → aws_durable_execution_sdk_python_otel-1.1.0}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling!=1.32.1,<1.33"]
 build-backend = "hatchling.build"
 
 [project]
@@ -22,7 +22,7 @@ classifiers = [
   "Programming Language :: Python :: Implementation :: PyPy",
 ]
 dependencies = [
-  "aws-durable-execution-sdk-python>=2.0.0",
+  "aws-durable-execution-sdk-python>=2.1.0",
 ]
 
 [project.entry-points."aws_durable_execution.plugins"]

{aws_durable_execution_sdk_python_otel-1.0.0 → aws_durable_execution_sdk_python_otel-1.1.0}/src/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__ = "1.0.0"
+__version__ = "1.1.0"

{aws_durable_execution_sdk_python_otel-1.0.0 → aws_durable_execution_sdk_python_otel-1.1.0}/src/aws_durable_execution_sdk_python_otel/deterministic_id_generator.py

@@ -21,6 +21,8 @@ if TYPE_CHECKING:
 class _IdOverride:
     trace_id: int | None
     span_id: int | None
+    trace_id_consumed: bool = False
+    consume_trace_id: bool = False
 
 
 def _to_otel_trace_id(execution_arn: str, start_timestamp: datetime) -> int:
@@ -83,9 +85,10 @@ def derive_workflow_span_id(durable_execution_arn: str) -> int:
 def derive_execution_root_span_id(durable_execution_arn: str) -> int:
     """Derive the deterministic synthetic execution-root span ID.
 
-    The synthetic root is a non-recording parent context used when the backend
-    does not provide a complete remote parent. Its ID is stable across
-    reinvocations and uses a namespace distinct from Workflow and operation
+    The synthetic root anchors the trace when the backend does not provide a
+    complete remote parent. Its zero-duration span is exported on each sampled
+    fallback invocation. Its ID is stable across reinvocations and uses a
+    namespace distinct from Workflow and operation
     span IDs.
     """
     if not durable_execution_arn:
@@ -143,28 +146,61 @@ class DeterministicIdGenerator(RandomIdGenerator):
         finally:
             self._id_override.reset(token)
 
+    @contextmanager
+    def _use_ids_for_span(
+        self,
+        *,
+        trace_id: int,
+        span_id: int,
+    ) -> Iterator[None]:
+        """Reserve IDs for one SDK-created span without changing public scope semantics."""
+        token = self._id_override.set(
+            _IdOverride(trace_id, span_id, consume_trace_id=True)
+        )
+        try:
+            yield
+        finally:
+            self._id_override.reset(token)
+
     def generate_trace_id(self) -> int:
         """Generate a 128-bit trace ID."""
         override = self._id_override.get()
         if override is not None and override.trace_id is not None:
+            # Consume the identity once, but keep its non-random classification
+            # until the SDK asks for the span ID below.
+            if override.consume_trace_id:
+                self._id_override.set(_IdOverride(None, override.span_id, True, True))
             return override.trace_id
+        if override is not None and override.trace_id_consumed:
+            self._id_override.set(
+                _IdOverride(
+                    None, override.span_id, consume_trace_id=override.consume_trace_id
+                )
+            )
         return self._fallback_id_generator.generate_trace_id()
 
     def generate_span_id(self) -> int:
         """Generate a 64-bit span ID."""
         override = self._id_override.get()
-        if override is not None and override.span_id is not None:
-            span_id = override.span_id
-            # Consume before returning so a re-entrant call in the same span
-            # creation falls back instead of reusing the deterministic ID.
-            self._id_override.set(_IdOverride(override.trace_id, None))
-            return span_id
+        if override is not None:
+            # Span ID generation completes the ID phase of SDK start_span, before
+            # processors run. Release the consumed trace classification too, so
+            # a processor creating another root sees only its own generator.
+            self._id_override.set(
+                _IdOverride(
+                    override.trace_id, None, consume_trace_id=override.consume_trace_id
+                )
+            )
+            if override.span_id is not None:
+                return override.span_id
         return self._fallback_id_generator.generate_span_id()
 
     def is_trace_id_random(self) -> bool:
         """Report whether the current trace ID is randomly generated."""
         override = self._id_override.get()
-        if override is not None and override.trace_id is not None:
+        if override is not None and (
+            override.trace_id is not None or override.trace_id_consumed
+        ):
             return False
         fallback_method = getattr(
             self._fallback_id_generator, "is_trace_id_random", None

{aws_durable_execution_sdk_python_otel-1.0.0 → aws_durable_execution_sdk_python_otel-1.1.0}/src/aws_durable_execution_sdk_python_otel/durable_sampling.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import functools
 import inspect
 from dataclasses import dataclass
+from threading import Lock
 from typing import Any
 
 from opentelemetry import context as otel_context
@@ -31,6 +32,20 @@ class DurableSamplingIntent:
     result: SamplingResult
 
 
+class _SamplingIntentDelivery:
+    """Give one sampler call the intent, even if its context is forwarded."""
+
+    def __init__(self, intent: DurableSamplingIntent) -> None:
+        self._intent: DurableSamplingIntent | None = intent
+        self._lock = Lock()
+
+    def consume(self) -> DurableSamplingIntent | None:
+        with self._lock:
+            intent = self._intent
+            self._intent = None
+            return intent
+
+
 class DurableSampler(Sampler):
     """Sampler that honors a durable sampling intent carried on parent context."""
 
@@ -56,8 +71,13 @@ class DurableSampler(Sampler):
         links: Any = None,
         trace_state: Any = None,
     ) -> SamplingResult:
-        intent = otel_context.get_value(_DURABLE_SAMPLING_INTENT_KEY, parent_context)
-        if isinstance(intent, DurableSamplingIntent):
+        delivery = otel_context.get_value(_DURABLE_SAMPLING_INTENT_KEY, parent_context)
+        intent = (
+            delivery.consume()
+            if isinstance(delivery, _SamplingIntentDelivery)
+            else None
+        )
+        if intent is not None:
             merged_attributes = dict(attributes or {})
             merged_attributes.update(dict(intent.result.attributes or {}))
             return SamplingResult(
@@ -84,10 +104,17 @@ def store_sampling_intent(
     parent_context: Context,
     intent: DurableSamplingIntent | None,
 ) -> Context:
-    """Attach a durable sampling intent to a span parent context."""
+    """Attach a fresh single-use delivery of the invocation's sampling result.
+
+    The sampler consumes it before processors run. A processor forwarding this
+    context therefore uses its own sampling policy; another durable span gets a
+    new delivery without changing the reusable invocation-level intent.
+    """
     if intent is None:
         return parent_context
-    return otel_context.set_value(_DURABLE_SAMPLING_INTENT_KEY, intent, parent_context)
+    return otel_context.set_value(
+        _DURABLE_SAMPLING_INTENT_KEY, _SamplingIntentDelivery(intent), parent_context
+    )
 
 
 def resolve_sampling_result(