Skip to content

feat: add unified OTel plugin factory - #873

Merged
zhongkechen merged 6 commits into
aws:mainfrom
zhongkechen:feat/unified-otel-factory-872
Nov 4, 2026
Merged

zhongkechen merged 6 commits into
aws:mainfrom
zhongkechen:feat/unified-otel-factory-872

Conversation

@zhongkechen

@zhongkechen zhongkechen commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Users currently select between two OTel factory names before registering tracing. Add OtelPlugin.factory(...) as a single entry point: execution view is the default, Mode.INVOCATION selects invocation view, and both accept existing configuration and provider-builder paths. DURABLE_EXECUTION_PLUGINS=otel loads the default view through ServiceLoader.

Issue Link

Closes #872. Related implementations: aws/aws-durable-execution-sdk-python#904 and aws/aws-durable-execution-sdk-js#1170. The SDK additions can merge independently; cross-language documentation can follow once the APIs are released.

Description

Existing factories and provider names remain supported. The selector returns the existing factory directly, preserving exclusive-group metadata and per-invocation instances. The three ServiceLoader providers share an internal delegate while retaining their public classes and original class hierarchy. README examples cover both views and loading without handler changes. Configure only one environment alias: listing both otel and otel-execution fails exclusive-group validation.

Demo/Screenshots

OtelPlugin.factory(); // execution view
OtelPlugin.factory(OtelPlugin.Mode.INVOCATION); // invocation view

Register one returned factory with DurableConfig.builder().withPlugins(...), or select DURABLE_EXECUTION_PLUGINS=otel without handler-side registration.

Design

Design note: #872 and the following analysis implement the requested additive API.

  • Problem: Code-based registration requires choosing between separate factory names; environment registration has no short default entry point.
  • Cause: Each view exposes its own API and ServiceLoader name. This is an enhancement, not a bug fix.
  • Simpler options: Documentation alone leaves separate entry points. Moving existing APIs breaks callers. Merging the view implementations adds unrelated lifecycle risk. A selector can reuse both factories and retain their identity.
  • Choice: Add a small selector and the otel alias, leaving lifecycle and tracing behavior in the existing implementations.
  • Removals: None. Public additions: OtelPlugin, its Mode enum with two constants, five factory overloads, and the OtelPluginProvider SPI implementation.

Assumptions

  • Factory selection preserves lifecycle and telemetry semantics: covered through real LocalDurableTestRunner suspension/resume and concurrent executions, and the full OTel suite.
  • ServiceLoader discovers the aliases from the packaged plugin: verified in forked environment-loading tests and a standalone JDK 17 probe against the built JAR.
  • Global-provider integration is tested against a locally configured OpenTelemetry SDK with the deterministic ID generator installed as ADOT does. Live ADOT/Lambda layer deployment remains unverified; cloud/conformance runs were not performed for this API-only addition.

Decisions not covered by the issue or the design note

  • factory() supplies the zero-configuration execution default. All configured/provider overloads take Mode first.
  • A null mode throws NullPointerException at selection time, before a provider builder is touched, consistent with existing configuration null validation.
  • No deprecation is introduced; this change only adds the unified entry point.
  • Shared provider logic uses composition to preserve source compatibility for inferred mixed-provider collections, as well as public signatures and ServiceLoader behavior.

Checklist

  • I have filled out every section of the PR template.
  • I have thoroughly tested this change locally; cloud limits are listed above.
  • Every new selection branch has a test that fails without it.
  • Bug-fix regression requirement: not applicable, this adds a feature.
  • Edited test expectations: the configuration integration test now reads MdcSpanEnricher.MDC_TRACE_ID (traceId) rather than the unused trace_id key. The existing environment-loading test adds otel while retaining its original assertions and aliases.

Testing

  • mvn -o -pl otel-plugin -am spotless:check test on Java 17: 2652 tests passed, 5 skipped, zero failures/errors across the SDK, testing utilities, and OTel plugin. Spotless passed.
  • Focused unified-factory, registration, replay, and legacy-provider tests: 38 passed, zero failures/errors/skips.
  • External Java 17-source compatibility probes confirm mixed-provider collections still compile unchanged. Previously compiled callers run against the refactored providers, ServiceLoader discovery passes, and javap -public signatures are unchanged for all three providers.
  • Countercheck of the MDC test in both views: with MDC temporarily enabled, the original wrong-key assertion passed both cases; the corrected constant-based assertion failed both cases. The final tests restore enableMdc(false) and pass, so the assertion now detects an ignored logging option.

Unit Tests

Added mode/default selection, null-mode rejection before provider initialization, existing null-config validation, lazy global-provider setup, and ServiceLoader alias tests.

Integration Tests

Added configuration forwarding, global-provider setup, initial invocation and replay, concurrent execution isolation, and new-alias/environment exclusivity coverage through the real SDK. Existing explicit-factory exclusivity tests retain that coverage without repeating it through the selector.

Examples

Updated the OTel README with execution and invocation factory examples, custom provider configuration, and the otel environment alias. Existing view-specific examples remain valid.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Companion SDK pull requests

These SDK changes can merge independently. Cross-language guide updates can follow the corresponding package releases.

@zhongkechen
zhongkechen requested a review from a team November 3, 2026 21:08
@zhongkechen
zhongkechen temporarily deployed to ai-pr-review-runtime November 3, 2026 21:08 — with GitHub Actions Inactive
zhongkechen added a commit to aws/aws-durable-execution-sdk-js that referenced this pull request Nov 3, 2026
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license.

### Issue Link, if available

Closes #1170.
Related implementations: [Java
#872](aws/aws-durable-execution-sdk-java#872),
[Python
#904](aws/aws-durable-execution-sdk-python#904).

### Description

Users can select either OTel view through `createOtelPluginFactory()`,
with execution as the default and `{ mode: "invocation" }` selecting
invocation mode. The factory snapshots existing configuration values and
returns the original implementation's factory, preserving its
registration metadata and per-invocation lifecycle. Existing factory
exports and provider subpaths remain supported.

The package root now exports the existing lazy execution provider,
allowing `DURABLE_EXECUTION_PLUGINS=@aws/durable-execution-sdk-js-otel`
without handler-side plugin registration. The provider/exporter must
still be configured by ADOT or the application.

### Demo/Screenshots

```typescript
import { createOtelPluginFactory } from "@aws/durable-execution-sdk-js-otel";

createOtelPluginFactory();
createOtelPluginFactory({ mode: "invocation", enrichLogger: false });
```

Both results are factories for the handler's `plugins` list. The README
and new `otel/unified-factory` example demonstrate registration and
durable resume.

### Design

Design note: #1170 describes the selector design.

1. **Problem:** Selecting a view requires different imports, and
environment loading has no default package-root entry point.
2. **Cause:** The package exposes two separate factory constructors and
two provider subpaths.
3. **Options:** Replacing the old factories breaks callers; merging the
implementations adds unnecessary lifecycle and telemetry risk. A small
selector can reuse the existing factories unchanged.
4. **Chosen:** Export `createOtelPluginFactory(options?)`, following the
existing `createExecutionOtelPluginFactory` and
`createInvocationOtelPluginFactory` naming. Resolve mode once, reject
unsupported modes, and return the selected factory directly. Re-export
the existing execution provider at the root to retain lazy
initialization and metadata without another wrapper.
5. **Removals:** None. No SDK invariant or telemetry behavior changes.

Net OTel runtime source change: +36 lines. Three new named exports:
`createOtelPluginFactory`, `OtelPluginFactoryOptions`, and
`durableExecutionPluginProvider`.
Root cause for a bug fix: not applicable; this is an additive feature.

### Assumptions

- Factory registration, exclusivity, concurrent execution isolation, and
replay are exercised with the current real core SDK and local runner.
Provider behavior is tested with the actual OpenTelemetry SDK and
in-memory exporter.
- Packed ESM/CommonJS exports, package-root environment loading, both
existing subpaths, and public typings were checked using isolated
installed-package fixtures rebuilt from this checkout.
- **Unverified:** Live Lambda/ADOT deployment and Node.js 22 runtime
execution. Local validation used Node.js 24.21.0; no AWS deployments
were run.

### Decisions not covered by the issue or the design note

- The unified entry point is a plain `createOtelPluginFactory` function,
matching the existing JavaScript factory API and avoiding a public
holder object. It returns the selected factory unchanged.
- Invalid explicit modes, including `null`, throw `TypeError`;
omitted/undefined modes default to execution.
- `createOtelPluginFactory(options)` shallow-copies the configuration
when the factory is created, so later assignments to the caller's
options cannot change the selected configuration. The existing factories
keep their current behavior: they read the original configuration object
on the first invocation.
- The unified-factory example is `localOnly: true`: its test retains
workflow/history coverage, while the OTel integration test covers
telemetry in both modes. This avoids a redundant cloud deployment and
intentionally leaves the example out of `template.yml`.
- Exact-optional consumer checks use `skipLibCheck` for existing
unrelated core logger declaration errors, matching the established
installed-header fixture. A separate normal strict check validates
declarations without that skip.

### Checklist

- [x] I have filled out every section of the PR template
- [x] I have thoroughly tested this change
- [x] Every new branch has a test that fails without it
(default/execution, invocation, and invalid mode)
- [x] For a bug fix: not applicable
- [x] Every edited test expectation is listed: the new invalid-mode test
now checks `TypeError` as well as the existing error message, protecting
the documented error contract. No pre-existing test expectations were
changed.

### Testing

- Focused OTel factory unit, composed, integration, and
packaged-consumer tests: **4 files, 27 tests passed**. Global setup
rebuilt core, testing SDK, and OTel CJS/ESM/declarations first. These
cover mode selection, configuration forwarding,
registration/exclusivity, replay/concurrency, and packed ESM/CommonJS
imports and public typings for `createOtelPluginFactory`.
- `npx tsc --noEmit --project
packages/aws-durable-execution-sdk-js-otel/tsconfig.json`: passed.
- `npm run lint -- --max-diagnostics=20`: passed, 1,329 files checked.
- The unified-factory example's local test passed against the rebuilt
candidate packages, including recorded-history validation.
- The actual SAM generator was checked with the example's `localOnly`
configuration: it excludes the example from local and integration
templates; a negative control with `localOnly: false` emits the
function.

#### Unit Tests

Added default/explicit selection, configuration forwarding, factory
identity/registration metadata, invalid-mode error type and message,
mode snapshotting, and import/provider laziness checks.

#### Integration Tests

Added real-loader exclusivity checks, concurrent public handlers with
suspension/replay, and packed ESM/CommonJS/type/environment-loading
checks. No new language-neutral conformance requirement is needed
because telemetry semantics are unchanged.

#### Examples

Added `otel/unified-factory` with a durable step/wait/resume workflow
and a local-only recorded-history test. The sample is excluded from
generated SAM templates and cloud integration deployment; telemetry
assertions remain in the OTel package integration test. Updated OTel
README usage and environment-loading guidance.

### Companion SDK pull requests

- [Java](aws/aws-durable-execution-sdk-java#873)
-
[Python](aws/aws-durable-execution-sdk-python#905)

These SDK changes can merge independently. Cross-language guide updates
can follow the corresponding package releases.

---------

Co-authored-by: Silan He <16982279+SilanHe@users.noreply.github.com>
Review feedback on aws#873.

`otel` loads the same view as `otel-execution` through a separate
provider, so listing both puts two factories in the `durable-otel-view`
group and the function fails at startup. That message interpolates the
provider objects, and none of them overrode `toString`, so it reported
identity hashes rather than the `DURABLE_EXECUTION_PLUGINS` values the
operator set. All three OTel providers now describe themselves as
`<entry-name> (<view>)`.

Drop the three `OtelPlugin.factory` overloads that omit `Mode` and
duplicate `ExecutionOtelPlugin.factory`, keeping the no-argument
default. Every call that passes configuration or a provider builder now
names its mode, which also lets an untyped `null` resolve without a
cast.

Document that calls are not memoized, that exactly one OTel entry name
must be set, and that the other SDKs enforce the same one-view contract
in their own idiom rather than identically.
Comment thread otel-plugin/README.md Resolved
Comment thread otel-plugin/README.md Resolved
@zhongkechen
zhongkechen merged commit 98c60fa into aws:main Nov 4, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Add a unified OtelPlugin factory with execution defaults

2 participants