feat(otel): fully enum-driven OtelPluginConfig (#612)

* feat(otel): InvocationOtelPlugin uses config

Replace InvocationOtelPlugin's legacy positional kwargs with a single
OtelPluginConfig, mirroring ExecutionOtelPlugin and the JS SDK plugins.
This adds use_default_tracer_provider, enable_http_instrumentation,
exporter_config, and propagators to the Invocation plugin.

Also align the default provider with JS: when no provider is supplied
the plugin auto-configures an OTLP provider (default_use_global=False)
instead of the global/ADOT provider. Pass use_default_tracer_provider
=True for the global (e.g. ADOT) provider.

Migrated test call sites and README snippets to OtelPluginConfig.
105/105 otel tests pass; ruff and mypy clean.

BREAKING CHANGE: InvocationOtelPlugin no longer accepts positional or
keyword arguments; pass an OtelPluginConfig instead, e.g.
InvocationOtelPlugin(OtelPluginConfig(tracer_provider=...)).

* fix(otel): example handlers use global provider

The two OTel example handlers used InvocationOtelPlugin() with no
config. Now that the plugin defaults to auto-configuring an OTLP
provider (localhost:4318), the example tests time out when no
collector is running. Pass
OtelPluginConfig(use_default_tracer_provider=True) so the examples use
the globally configured provider (a no-op proxy under test), matching
the conformance handler and the prior no-arg behavior.

* refactor(otel): resolve provider source via enum

Simplify the tracer-provider selection by resolving it once into an
explicit ProviderSource (EXPLICIT / GLOBAL / AUTO_OTLP) instead of
recomputing booleans in two places.

- Drop the default_use_global parameter from create_tracer_provider;
  both plugins now share the same auto-OTLP default, so the seam is
  dead weight.
- Make OtelPluginConfig.use_default_tracer_provider a plain bool
  (default False) instead of a tri-state Optional[bool].
- ProviderResult carries source; owns_provider is a derived property.
- register_standalone_instrumentations switches on result.source
  rather than (config.tracer_provider, use_default_tracer_provider).

Behavior is unchanged. 105/105 otel tests pass; ruff clean; mypy clean
(pre-existing optional-instrumentation import warnings only).

* refactor(otel): move ProviderSource enum into config

Move the ProviderSource enum into otel_plugin_config and add
resolve_provider_source() so the explicit > global > auto-OTLP precedence
lives in one place. create_tracer_provider becomes a straight switch on the
resolved source. Remove the redundant ProviderResult.owns_provider property
and the dead self._owns_provider fields in both plugins.

* refactor(otel): make config fully provider_source-driven

Replace the use_default_tracer_provider boolean with a provider_source:
ProviderSource field as the single driver of provider selection. tracer_provider
becomes the EXPLICIT-only field; __post_init__ validates that EXPLICIT has a
tracer_provider and GLOBAL/AUTO_OTLP do not. create_tracer_provider switches on
config.provider_source; the redundant resolve_provider_source helper is removed.
ExecutionOtelPlugin ambient-parenting now keys off ProviderSource.GLOBAL.

Tests migrate the explicit-provider+flag shortcut to monkeypatching
trace.get_tracer_provider with provider_source=GLOBAL, matching the existing
InvocationOtelPlugin integration test. Examples updated to provider_source=GLOBAL.

BREAKING CHANGE: use_default_tracer_provider is removed; pass
provider_source=ProviderSource.GLOBAL (ADOT) or ProviderSource.EXPLICIT with a
tracer_provider instead.

* style(otel): apply ruff format

* refactor(otel): default provider_source to GLOBAL

Default OtelPluginConfig.provider_source to ProviderSource.GLOBAL (use the
globally configured provider, e.g. the ADOT Lambda layer) instead of AUTO_OTLP.

* refactor(otel): make AUTO_OTLP branch explicit

Switch create_tracer_provider on each ProviderSource explicitly with an
exhaustive guard, so no branch reads as an implicit default (the default
GLOBAL lives on OtelPluginConfig.provider_source).

* ci: re-trigger ci

* docs(otel): correct provider_source default in comments

Docstrings and an inline comment described the old AUTO_OTLP default,
stating the plugin auto-configures an OTLP provider when nothing is
supplied. The default is now GLOBAL (uses the globally configured, e.g.
ADOT, provider); AUTO_OTLP is the opt-in for a plugin-owned provider.
Comment/docstring-only; no behavior change.

---------

Co-authored-by: silanhe <hsilan@amazon.com>

Author: SilanHe

packages/aws-durable-execution-sdk-python-examples/src/otel/otel_logger_example.py

@@ -16,7 +16,11 @@
 
 from typing import Any
 
-from aws_durable_execution_sdk_python_otel import InvocationOtelPlugin
+from aws_durable_execution_sdk_python_otel import (
+    InvocationOtelPlugin,
+    OtelPluginConfig,
+    ProviderSource,
+)
 
 from aws_durable_execution_sdk_python import StepContext
 from aws_durable_execution_sdk_python.context import (
@@ -44,7 +48,11 @@ def greet_in_child(child_context: DurableContext, name: str) -> str:
     return result
 
 
-@durable_execution(plugins=[InvocationOtelPlugin()])
+@durable_execution(
+    plugins=[
+        InvocationOtelPlugin(OtelPluginConfig(provider_source=ProviderSource.GLOBAL))
+    ]
+)
 def handler(_event: Any, context: DurableContext) -> str:
     # Logged at the top level: enriched with the invocation span_id.
     context.logger.info("Workflow started")

packages/aws-durable-execution-sdk-python-examples/src/plugin/execution_with_otel.py

@@ -2,7 +2,11 @@
 
 from typing import Any
 
-from aws_durable_execution_sdk_python_otel import InvocationOtelPlugin
+from aws_durable_execution_sdk_python_otel import (
+    InvocationOtelPlugin,
+    OtelPluginConfig,
+    ProviderSource,
+)
 
 from aws_durable_execution_sdk_python import StepContext
 from aws_durable_execution_sdk_python.config import Duration
@@ -32,7 +36,11 @@ def add_numbers_in_child(child_context: DurableContext, a: int, b: int):
     return result
 
 
-@durable_execution(plugins=[InvocationOtelPlugin()])
+@durable_execution(
+    plugins=[
+        InvocationOtelPlugin(OtelPluginConfig(provider_source=ProviderSource.GLOBAL))
+    ]
+)
 def handler(_event: Any, context: DurableContext) -> int:
     result = 0
     for i in range(3):

packages/aws-durable-execution-sdk-python-otel/README.md

@@ -168,21 +168,25 @@ See the [ADOT sampling configuration](https://aws-otel.github.io/docs/getting-st
 ```python
 from aws_durable_execution_sdk_python_otel import (
     InvocationOtelPlugin,
+    OtelPluginConfig,
     xray_context_extractor,
 )
 
 plugin = InvocationOtelPlugin(
-    # 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,
+    OtelPluginConfig(
+        # Provide your own TracerProvider if you already have one configured.
+        # When omitted, an OTLP provider is auto-configured (like ExecutionOtelPlugin);
+        # set use_default_tracer_provider=True to use the global (e.g. ADOT) provider.
+        tracer_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,
+    )
 )
 ```
 
@@ -193,15 +197,16 @@ The plugin supports multiple strategies for extracting upstream trace context:
 ```python
 from aws_durable_execution_sdk_python_otel import (
     InvocationOtelPlugin,
+    OtelPluginConfig,
     w3c_client_context_extractor,
     xray_context_extractor,
 )
 
 # Default: X-Ray trace header (recommended for most Lambda deployments)
-InvocationOtelPlugin(context_extractor=xray_context_extractor)
+InvocationOtelPlugin(OtelPluginConfig(context_extractor=xray_context_extractor))
 
 # W3C Trace Context via clientContext (requires backend propagation support)
-InvocationOtelPlugin(context_extractor=w3c_client_context_extractor)
+InvocationOtelPlugin(OtelPluginConfig(context_extractor=w3c_client_context_extractor))
 ```
 
 ### Log Correlation
@@ -251,10 +256,15 @@ The main plugin class. Implements `DurableInstrumentationPlugin` from `aws_durab
 
 ```python
 InvocationOtelPlugin(
-    trace_provider=None,
-    context_extractor=None,
-    instrument_name="aws-durable-execution-sdk-python",
-    enrich_logger=True,
+    OtelPluginConfig(
+        tracer_provider=None,
+        context_extractor=None,
+        instrument_name="aws-durable-execution-sdk-python",
+        enrich_logger=True,
+        workflow_span_name="Workflow",
+        # ...and the rest of OtelPluginConfig (use_default_tracer_provider,
+        # enable_http_instrumentation, exporter_config, propagators).
+    )
 )
 ```
 

packages/aws-durable-execution-sdk-python-otel/src/aws_durable_execution_sdk_python_otel/__init__.py

@@ -17,6 +17,7 @@
 from aws_durable_execution_sdk_python_otel.otel_plugin_config import (
     OtelPluginConfig,
     ExporterConfig,
+    ProviderSource,
 )
 from aws_durable_execution_sdk_python_otel.instrumentations import (
     register_standalone_instrumentations,
@@ -44,6 +45,7 @@
     "InvocationOtelPlugin",
     "OtelContextLogFilter",
     "ProviderResult",
+    "ProviderSource",
     "create_tracer_provider",
     "derive_workflow_span_id",
     "install_log_filter",

packages/aws-durable-execution-sdk-python-otel/src/aws_durable_execution_sdk_python_otel/execution_plugin.py

@@ -62,6 +62,7 @@
 )
 from aws_durable_execution_sdk_python_otel.otel_plugin_config import (
     OtelPluginConfig,
+    ProviderSource,
 )
 from aws_durable_execution_sdk_python_otel.instrumentations import (
     register_standalone_instrumentations,
@@ -92,7 +93,8 @@ class ExecutionOtelPlugin(DurableInstrumentationPlugin):
 
     Args:
         config: Shared plugin configuration. When omitted, defaults are used
-            (auto-configured provider, X-Ray extractor, "Workflow" root span).
+            (globally configured provider, X-Ray extractor, "Workflow" root
+            span).
     """
 
     def __init__(self, config: OtelPluginConfig | None = None) -> None:
@@ -101,16 +103,17 @@ def __init__(self, config: OtelPluginConfig | None = None) -> None:
             self._config.context_extractor or xray_context_extractor
         )
         self._workflow_span_name = self._config.workflow_span_name
-        self._use_default = bool(self._config.use_default_tracer_provider)
 
         self._id_generator = DeterministicIdGenerator()
         result = create_tracer_provider(
             self._config,
             id_generator=self._id_generator,
-            default_use_global=False,
         )
         self._provider = result.tracer_provider
-        self._owns_provider = result.owns_provider
+        # GLOBAL (ADOT) mode parents the Invocation span to the ambient Lambda
+        # invocation span instead of the Workflow span (see
+        # _start_invocation_span).
+        self._provider_source = result.source
 
         # Deterministic stitching requires an SDK provider exposing id_generator.
         from opentelemetry.sdk.trace import TracerProvider as SdkTracerProvider
@@ -129,12 +132,7 @@ def __init__(self, config: OtelPluginConfig | None = None) -> None:
         self._tracer: Tracer = self._provider.get_tracer(self._config.instrument_name)
 
         try:
-            register_standalone_instrumentations(
-                self._config,
-                self._provider if self._owns_provider else None,
-                owns_provider=self._owns_provider,
-                use_default_tracer_provider=self._use_default,
-            )
+            register_standalone_instrumentations(self._config, result)
         except Exception:
             logger.exception("Failed to register standalone instrumentations")
 
@@ -244,7 +242,7 @@ def _start_workflow_span(self, info: InvocationStartInfo) -> None:
     def _start_invocation_span(self, info: InvocationStartInfo) -> None:
         self._id_generator.set_next_span_id(None)
         attributes: dict[str, Any]
-        if self._use_default:
+        if self._provider_source is ProviderSource.GLOBAL:
             # Default-provider mode: parent the Invocation span to the ambient
             # Lambda invocation span (from the ADOT layer or other
             # auto-instrumentation), which is still the active context here (the

packages/aws-durable-execution-sdk-python-otel/src/aws_durable_execution_sdk_python_otel/instrumentations.py

@@ -3,7 +3,7 @@
 Mirrors the JS ``registerStandaloneInstrumentations``:
 
 * A custom (explicit) provider skips ALL instrumentation registration.
-* When the global provider is in use (``use_default_tracer_provider``), only the
+* When the global provider is in use (``ProviderSource.GLOBAL``), only the
   AWS SDK instrumentation is registered (not HTTP).
 * When the plugin owns an auto-configured provider, both AWS SDK and (optionally)
   HTTP instrumentation are registered against that provider.
@@ -22,13 +22,14 @@
 import os
 from typing import TYPE_CHECKING, Any
 
+from aws_durable_execution_sdk_python_otel.otel_plugin_config import ProviderSource
 
-if TYPE_CHECKING:
-    from opentelemetry.trace import TracerProvider
 
+if TYPE_CHECKING:
     from aws_durable_execution_sdk_python_otel.otel_plugin_config import (
         OtelPluginConfig,
     )
+    from aws_durable_execution_sdk_python_otel.provider import ProviderResult
 
 
 logger = logging.getLogger(__name__)
@@ -98,31 +99,25 @@ def request_hook(span, pool, request_info) -> None:  # noqa: ANN001
 
 def register_standalone_instrumentations(
     config: OtelPluginConfig,
-    tracer_provider: TracerProvider | None,
-    *,
-    owns_provider: bool,
-    use_default_tracer_provider: bool,
+    result: ProviderResult,
 ) -> None:
-    """Register AWS SDK and HTTP instrumentations per the shared policy.
+    """Register AWS SDK and HTTP instrumentations per the resolved source.
 
     Args:
         config: Shared plugin configuration.
-        tracer_provider: The resolved provider (may be the global provider).
-        owns_provider: True when the plugin created/owns the provider.
-        use_default_tracer_provider: True when the global provider is in use.
+        result: The resolved provider and its :class:`ProviderSource`.
     """
-    # A custom, explicitly-supplied provider means the caller manages their own
-    # instrumentation: skip everything.
-    if config.tracer_provider is not None:
+    if result.source is ProviderSource.EXPLICIT:
+        # Caller manages their own instrumentation: skip everything.
         return
 
-    if use_default_tracer_provider:
+    if result.source is ProviderSource.GLOBAL:
         # Global provider: register AWS instrumentation only.
         _register_aws_instrumentation(None)
         return
 
-    # Auto-configured, plugin-owned provider: AWS SDK always; HTTP unless
-    # explicitly disabled.
-    _register_aws_instrumentation(tracer_provider)
+    # AUTO_OTLP: auto-configured, plugin-owned provider -> AWS SDK always; HTTP
+    # unless explicitly disabled.
+    _register_aws_instrumentation(result.tracer_provider)
     if config.enable_http_instrumentation:
-        _register_http_instrumentation(tracer_provider)
+        _register_http_instrumentation(result.tracer_provider)

packages/aws-durable-execution-sdk-python-otel/src/aws_durable_execution_sdk_python_otel/invocation_plugin.py

@@ -45,7 +45,11 @@
 )
 from aws_durable_execution_sdk_python_otel.log_filter import install_log_filter
 from aws_durable_execution_sdk_python_otel.otel_plugin_config import (
-    DEFAULT_WORKFLOW_SPAN_NAME,
+    OtelPluginConfig,
+)
+from aws_durable_execution_sdk_python_otel.provider import create_tracer_provider
+from aws_durable_execution_sdk_python_otel.instrumentations import (
+    register_standalone_instrumentations,
 )
 
 
@@ -80,42 +84,56 @@ class InvocationOtelPlugin(DurableInstrumentationPlugin):
     original logical operation.
 
     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.
-        instrument_name: Instrumentation scope name registered with the tracer.
+        config: Shared plugin configuration (the same OtelPluginConfig accepted
+            by ExecutionOtelPlugin). When omitted, defaults are used (X-Ray
+            extractor, "Workflow" span name, log enrichment on). Like
+            ExecutionOtelPlugin and the JS SDK plugins, the default
+            ``provider_source`` is ``GLOBAL``: the plugin uses the globally
+            configured tracer provider (e.g. the ADOT Lambda layer). Set
+            ``provider_source=ProviderSource.AUTO_OTLP`` on the config to have
+            the plugin build and own an auto-configured OTLP provider instead.
     """
 
     DEFAULT_INSTRUMENT_NAME = "aws-durable-execution-sdk-python"
 
-    def __init__(
-        self,
-        trace_provider: SdkTracerProvider | None = None,
-        context_extractor: ContextExtractor | None = None,
-        instrument_name: str = DEFAULT_INSTRUMENT_NAME,
-        enrich_logger: bool = True,
-        workflow_span_name: str = DEFAULT_WORKFLOW_SPAN_NAME,
-    ) -> None:
-        """Initialize the plugin with an OpenTelemetry tracer provider.
+    def __init__(self, config: OtelPluginConfig | None = None) -> None:
+        """Initialize the plugin from a shared OtelPluginConfig.
+
+        Accepts the same OtelPluginConfig as ExecutionOtelPlugin so both plugins
+        share one configuration surface (context extractor, instrumentation
+        name, provider selection, exporter/propagator settings, log
+        enrichment). Like ExecutionOtelPlugin and the JS SDK plugins, the
+        default ``provider_source`` is ``GLOBAL``: it uses the globally
+        configured (e.g. ADOT) provider. Pass
+        ``provider_source=ProviderSource.AUTO_OTLP`` to have the plugin build
+        and own an auto-configured OTLP provider instead.
 
         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.
+        logical operation identifiers.
 
-        When enrich_logger is enabled (default), the plugin installs a logging
-        filter on the root logger at invocation start that stamps the active
-        OTel trace context onto every emitted log record.
+        When ``enrich_logger`` is enabled (default), the plugin installs a
+        logging filter that stamps the active OTel trace context onto every
+        emitted log record.
         """
-        self._enrich_logger = enrich_logger
-        self._workflow_span_name = workflow_span_name
+        self._config = config or OtelPluginConfig()
         self._context_extractor: ContextExtractor = (
-            context_extractor or xray_context_extractor
+            self._config.context_extractor or xray_context_extractor
         )
+        self._workflow_span_name = self._config.workflow_span_name
+        self._enrich_logger = self._config.enrich_logger
+
+        # Like ExecutionOtelPlugin (and the JS SDK plugins), InvocationOtelPlugin
+        # defaults to provider_source=GLOBAL (the globally configured, e.g. ADOT,
+        # provider); set provider_source=ProviderSource.AUTO_OTLP on the config
+        # to build and own an auto-configured OTLP provider instead.
+        self._id_generator = DeterministicIdGenerator()
+        result = create_tracer_provider(
+            self._config,
+            id_generator=self._id_generator,
+        )
+        self._provider = result.tracer_provider
 
-        self._provider = trace_provider or trace.get_tracer_provider()
         # 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
@@ -128,16 +146,20 @@ def __init__(
                 self._provider
             )
         else:
-            self._id_generator = DeterministicIdGenerator()
             logger.warning(
                 "InvocationOtelPlugin 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.",
+                "Lambda layer) or pass an explicit tracer_provider.",
                 type(self._provider).__name__,
             )
-        self._tracer: Tracer = self._provider.get_tracer(instrument_name)
+        self._tracer: Tracer = self._provider.get_tracer(self._config.instrument_name)
+
+        try:
+            register_standalone_instrumentations(self._config, result)
+        except Exception:
+            logger.exception("Failed to register standalone instrumentations")
 
         # per invocation status:
         self._execution_arn = ""