aws-durable-execution-sdk-python-otel 0.1.0__tar.gz → 0.2.0__tar.gz

{aws_durable_execution_sdk_python_otel-0.1.0 → aws_durable_execution_sdk_python_otel-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aws-durable-execution-sdk-python-otel
-Version: 0.1.0
+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
@@ -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 :: 1 - Planning
+Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -17,13 +17,50 @@ 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:** This release reserves the package name. Full instrumentation is coming soon.
+> **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
 

aws_durable_execution_sdk_python_otel-0.2.0/README.md

@@ -0,0 +1,41 @@
+# 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.1.0 → aws_durable_execution_sdk_python_otel-0.2.0}/pyproject.toml

@@ -12,7 +12,7 @@ license = "Apache-2.0"
 keywords = ["opentelemetry", "tracing", "observability", "durable-execution"]
 authors = [{ name = "AWS durable-execution-dev", email = "durable-execution-dev@amazon.com" }]
 classifiers = [
-  "Development Status :: 1 - Planning",
+  "Development Status :: 4 - Beta",
   "Programming Language :: Python",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
@@ -21,7 +21,13 @@ classifiers = [
   "Programming Language :: Python :: Implementation :: CPython",
   "Programming Language :: Python :: Implementation :: PyPy",
 ]
-dependencies = []
+dependencies = [
+  "aws-durable-execution-sdk-python>=1.5.0",
+  "opentelemetry-api>=1.20.0",
+  "opentelemetry-sdk>=1.20.0",
+  "opentelemetry-exporter-otlp",
+  "opentelemetry-propagator-aws-xray",
+]
 
 [project.urls]
 Documentation = "https://github.com/aws/aws-durable-execution-sdk-python#readme"
@@ -41,3 +47,46 @@ packages = ["src/aws_durable_execution_sdk_python_otel"]
 
 [tool.hatch.version]
 path = "src/aws_durable_execution_sdk_python_otel/__about__.py"
+
+[tool.hatch.publish.index]
+disable = true
+
+[tool.coverage.run]
+source_pkgs = ["aws_durable_execution_sdk_python_otel"]
+branch = true
+parallel = true
+omit = ["src/aws_durable_execution_sdk_python_otel/__about__.py"]
+
+[tool.coverage.paths]
+aws_durable_execution_sdk_python_otel = [
+  "src/aws_durable_execution_sdk_python_otel",
+  "*/aws-durable-execution-sdk-python-otel/src/aws_durable_execution_sdk_python_otel",
+]
+
+[tool.coverage.report]
+exclude_lines = ["no cov", "if __name__ == .__main__.:", "if TYPE_CHECKING:"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+preview = true
+select = ["TID252"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["aws_durable_execution_sdk_python_otel"]
+force-single-line = false
+lines-after-imports = 2
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+  "ARG001",
+  "ARG002",
+  "ARG005",
+  "S101",
+  "PLR2004",
+  "PLR6301",
+  "SIM117",
+  "TRY301",
+]

{aws_durable_execution_sdk_python_otel-0.1.0 → aws_durable_execution_sdk_python_otel-0.2.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__ = "0.1.0"
+__version__ = "0.2.0"

aws_durable_execution_sdk_python_otel-0.2.0/src/aws_durable_execution_sdk_python_otel/__init__.py

@@ -0,0 +1,30 @@
+"""OpenTelemetry instrumentation for AWS Lambda Durable Executions Python SDK."""
+
+from aws_durable_execution_sdk_python_otel.__about__ import __version__
+from aws_durable_execution_sdk_python_otel.context_extractors import (
+    ContextExtractor,
+    w3c_client_context_extractor,
+    xray_context_extractor,
+)
+from aws_durable_execution_sdk_python_otel.deterministic_id_generator import (
+    DeterministicIdGenerator,
+)
+from aws_durable_execution_sdk_python_otel.log_filter import (
+    OtelContextLogFilter,
+    install_log_filter,
+)
+from aws_durable_execution_sdk_python_otel.plugin import (
+    DurableExecutionOtelPlugin,
+)
+
+
+__all__ = [
+    "__version__",
+    "ContextExtractor",
+    "DeterministicIdGenerator",
+    "DurableExecutionOtelPlugin",
+    "OtelContextLogFilter",
+    "install_log_filter",
+    "w3c_client_context_extractor",
+    "xray_context_extractor",
+]

aws_durable_execution_sdk_python_otel-0.2.0/src/aws_durable_execution_sdk_python_otel/context_extractors.py

@@ -0,0 +1,40 @@
+"""Context extractors for propagating trace context into durable executions."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Callable
+
+from opentelemetry import context as otel_context, propagate
+
+
+if TYPE_CHECKING:
+    from opentelemetry.context import Context
+
+    from aws_durable_execution_sdk_python.plugin import InvocationStartInfo
+
+ContextExtractor = Callable[["InvocationStartInfo"], "Context"]
+
+
+def xray_context_extractor(info: "InvocationStartInfo") -> "Context":
+    """Read the X-Ray trace header from the _X_AMZN_TRACE_ID environment variable.
+
+    The durable execution backend propagates the same Root trace ID to every
+    invocation, so all invocations share one traceId.
+    """
+    trace_header = os.environ.get("_X_AMZN_TRACE_ID")
+    if not trace_header:
+        return otel_context.get_current()
+    return propagate.extract(
+        carrier={"X-Amzn-Trace-Id": trace_header},
+        context=otel_context.get_current(),
+    )
+
+
+def w3c_client_context_extractor(info: "InvocationStartInfo") -> "Context":
+    """Read W3C traceparent from context.clientContext.custom.traceparent.
+
+    Requires the backend clientContext propagation to be enabled.
+    This extractor is a placeholder for when backend propagation is supported.
+    """
+    return otel_context.get_current()

aws_durable_execution_sdk_python_otel-0.2.0/src/aws_durable_execution_sdk_python_otel/deterministic_id_generator.py

@@ -0,0 +1,126 @@
+"""Deterministic ID generator for OpenTelemetry spans in durable executions."""
+
+from __future__ import annotations
+
+import contextvars
+import hashlib
+import os
+import re
+from datetime import UTC, datetime
+
+from opentelemetry.sdk.trace import IdGenerator, RandomIdGenerator
+
+
+HASHED_ID_PATTERN = re.compile(r"^[0-9a-f]{16}$")
+
+# Scoping the pending span ID to the execution context ensures concurrent
+# operations cannot consume each other's deterministic span ID.
+_next_span_id: contextvars.ContextVar[int | None] = contextvars.ContextVar(
+    "next_span_id", default=None
+)
+
+
+def _parse_xray_root_trace_id(trace_header: str | None) -> str | None:
+    """Parse the Root trace ID from an X-Ray trace header string.
+
+    The header format is:
+      Root=1-<8 hex>-<24 hex>;Parent=<16 hex>;Sampled=0|1
+
+    Returns the root value (e.g. "1-5759e988-bd862e3fe1be46a994272793")
+    or None if the header is missing or malformed.
+    """
+    if not trace_header:
+        return None
+    match = re.search(r"Root=(1-[0-9a-fA-F]{8}-[0-9a-fA-F]{24})", trace_header)
+    return match.group(1) if match else None
+
+
+def _xray_trace_id_to_otel(xray_trace_id: str) -> int:
+    """Convert an X-Ray trace ID to the W3C/OpenTelemetry 32-char hex format.
+
+    X-Ray format: "1-<8hex>-<24hex>" (36 chars with prefix and dashes)
+    OTel format:  "<8hex><24hex>" (32 lowercase hex chars)
+    """
+    otel_id = xray_trace_id.replace("1-", "", 1).replace("-", "").lower()
+    return int(otel_id, 16)
+
+
+def _to_otel_trace_id(execution_arn: str, start_timestamp: datetime | None) -> int:
+    """Build an OTel-compatible trace ID (128 bits)
+
+    First attempts to read the trace ID from the _X_AMZN_TRACE_ID environment
+    variable that Lambda populates on each invocation. This ties the durable
+    execution spans to the same trace that X-Ray is already tracking.
+
+    Falls back to generating a deterministic trace ID from the execution ARN
+    and timestamp when the environment variable is not set (e.g. in tests or
+    non-Lambda environments).
+    """
+    env_trace_id = _parse_xray_root_trace_id(os.environ.get("_X_AMZN_TRACE_ID"))
+    if env_trace_id:
+        return _xray_trace_id_to_otel(env_trace_id)
+
+    # Fallback: deterministic ID from execution ARN + timestamp
+    time_part = format(int((start_timestamp or datetime.now(UTC)).timestamp()), "08x")
+    hash_part = hashlib.blake2b(execution_arn.encode()).hexdigest()[:24]  # noqa: S324
+    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]
+    return int(hashed_operation_id, 16)
+
+
+class DeterministicIdGenerator(RandomIdGenerator):
+    """An ID generator that produces deterministic span IDs when a pending
+    operation ID is set, and falls back to the provided generator otherwise.
+
+    Trace IDs are deterministic when an execution ARN is set, ensuring all
+    invocations of the same durable execution share a single trace. When no
+    deterministic ID is available, generation is delegated to the fallback
+    generator (the tracer provider's original ID generator by default).
+
+    Trace IDs embed a real timestamp so they satisfy the X-Ray format
+    requirement (first 8 hex chars = Unix epoch seconds).
+
+    Args:
+        fallback_id_generator: Generator used when no deterministic ID is
+            available. Defaults to a new ``RandomIdGenerator``.
+    """
+
+    def __init__(self, fallback_id_generator: IdGenerator | None = None) -> None:
+        self._execution_trace_id: int | None = None
+        self._fallback_id_generator = fallback_id_generator or RandomIdGenerator()
+
+    def set_next_span_id(self, span_id: int | None) -> None:
+        """Set the operation ID to use for the next span's ID.
+
+        After one span is created, it resets to random.
+        """
+        _next_span_id.set(span_id)
+
+    def set_trace_id(
+        self, execution_arn: str, start_timestamp: datetime | None
+    ) -> None:
+        """Compute and cache the deterministic trace ID for this execution.
+
+        Args:
+            execution_arn: The durable execution ARN (used for the hash portion).
+            start_timestamp: start time of invocation
+        """
+        self._execution_trace_id = _to_otel_trace_id(execution_arn, start_timestamp)
+
+    def generate_trace_id(self) -> int:
+        """Generate a 128-bit trace ID."""
+        return (
+            self._execution_trace_id or self._fallback_id_generator.generate_trace_id()
+        )
+
+    def generate_span_id(self) -> int:
+        """Generate a 64-bit span ID."""
+        span_id = _next_span_id.get()
+        # Consume once: the deterministic ID applies only to the next span
+        # created in this context; subsequent spans fall back to random.
+        _next_span_id.set(None)
+        return span_id or self._fallback_id_generator.generate_span_id()

aws_durable_execution_sdk_python_otel-0.2.0/src/aws_durable_execution_sdk_python_otel/log_filter.py

@@ -0,0 +1,105 @@
+"""Root-logger filter that stamps OTel trace context onto every log record.
+
+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):
+
+    - ``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
+
+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
+unmodified, so any log formatter or schema must treat the fields as optional.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from opentelemetry.trace import TraceFlags
+
+
+if TYPE_CHECKING:
+    from aws_durable_execution_sdk_python_otel.plugin import DurableExecutionOtelPlugin
+
+
+class OtelContextLogFilter(logging.Filter):
+    """Logging filter that injects the active OTel span context onto records.
+
+    The filter is a pure reader of the plugin's current span context. It
+    resolves the span at emit time, on the thread that emits the record, via
+    ``plugin.get_current_span_context()``. That method returns the active
+    operation span inside steps and child contexts (attached to the worker
+    thread's OTel context) and falls back to the invocation span for top-level
+    handler code.
+
+    The filter never caches identifiers and always returns ``True`` so it never
+    drops a record.
+
+    Args:
+        plugin: The OTel plugin instance that resolves the current span context.
+    """
+
+    def __init__(self, plugin: DurableExecutionOtelPlugin) -> None:
+        super().__init__()
+        self._plugin = plugin
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """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(
+                span_context.trace_flags & TraceFlags.SAMPLED
+            )
+        return True
+
+
+def install_log_filter(
+    plugin: DurableExecutionOtelPlugin,
+    target_logger: logging.Logger | None = None,
+) -> OtelContextLogFilter | None:
+    """Attach an OtelContextLogFilter to a logger's handlers, idempotently.
+
+    The filter is attached to each handler on ``target_logger`` (the root logger
+    by default). Attaching to handlers rather than the logger itself ensures
+    records propagated from child loggers are also enriched, since handler
+    filters run for every record reaching the handler.
+
+    This is safe to call on every invocation: if a handler already has an
+    OtelContextLogFilter, it is left as-is, so warm Lambda reuse will not stack
+    duplicate filters. A single shared filter instance is reused across all
+    handlers.
+
+    Args:
+        plugin: The OTel plugin that resolves the current span context.
+        target_logger: Logger whose handlers receive the filter. Defaults to the
+            root logger, which in AWS Lambda is where runtime log handlers live.
+
+    Returns:
+        The filter instance attached to the handlers, or ``None`` if the target
+        logger has no handlers to attach to.
+    """
+    logger = target_logger if target_logger is not None else logging.getLogger()
+
+    context_filter: OtelContextLogFilter | None = None
+    for handler in logger.handlers:
+        existing = next(
+            (f for f in handler.filters if isinstance(f, OtelContextLogFilter)),
+            None,
+        )
+        if existing is not None:
+            # Reuse the already-installed filter so a single instance is shared.
+            context_filter = existing
+            continue
+        if context_filter is None:
+            context_filter = OtelContextLogFilter(plugin)
+        handler.addFilter(context_filter)
+
+    return context_filter