Repository navigation
feat: add unified OTel plugin factory - #873
Merged
Merged
Conversation
zhongkechen
temporarily deployed
to
ai-pr-review-runtime
November 3, 2026 21:08 — with
GitHub Actions
Inactive
This was referenced Nov 3, 2026
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.
SilanHe
approved these changes
Nov 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.INVOCATIONselects invocation view, and both accept existing configuration and provider-builder paths.DURABLE_EXECUTION_PLUGINS=otelloads 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
otelandotel-executionfails exclusive-group validation.Demo/Screenshots
Register one returned factory with
DurableConfig.builder().withPlugins(...), or selectDURABLE_EXECUTION_PLUGINS=otelwithout handler-side registration.Design
Design note: #872 and the following analysis implement the requested additive API.
otelalias, leaving lifecycle and tracing behavior in the existing implementations.OtelPlugin, itsModeenum with two constants, five factory overloads, and theOtelPluginProviderSPI implementation.Assumptions
LocalDurableTestRunnersuspension/resume and concurrent executions, and the full OTel suite.Decisions not covered by the issue or the design note
factory()supplies the zero-configuration execution default. All configured/provider overloads takeModefirst.NullPointerExceptionat selection time, before a provider builder is touched, consistent with existing configuration null validation.Checklist
MdcSpanEnricher.MDC_TRACE_ID(traceId) rather than the unusedtrace_idkey. The existing environment-loading test addsotelwhile retaining its original assertions and aliases.Testing
mvn -o -pl otel-plugin -am spotless:check teston Java 17: 2652 tests passed, 5 skipped, zero failures/errors across the SDK, testing utilities, and OTel plugin. Spotless passed.javap -publicsignatures are unchanged for all three providers.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
otelenvironment 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.