Skip to content

feat(plugin): prepare propagation metadata - #755

Draft
zhongkechen wants to merge 2 commits into
mainfrom
feature/otel-propagation-contract
Draft

zhongkechen wants to merge 2 commits into
mainfrom
feature/otel-propagation-contract

Conversation

@zhongkechen

@zhongkechen zhongkechen commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Refs #751. Coordinated groundwork: aws/aws-durable-execution-sdk-js#957 and aws/aws-durable-execution-sdk-java#764.

This model-blocked draft prepares the SDK-owned propagation contract, synchronous collector and pure OTel producers. It does not transmit metadata or implement the full chained-invoke feature. Public Lambda models currently lack ChainedInvokeOptions.XAmznTraceId and DistributedMapOptions; production invoke START and wire serialization remain unchanged.

The core contract adds frozen PropagationInput (execution ARN, operation ID, optional parent operation ID, target function name) and frozen PropagationMetadata with optional x_amzn_trace_id. The optional synchronous hook defaults to no contribution. Collection is ordered and first-non-null wins; equal values do not conflict, while different later values warn with both plugin identities and a running conflict count. Ordinary hook/getter/result/diagnostic failures are isolated, accidental coroutine returns are closed and rejected, and existing BaseException cancellation/control semantics remain unchanged.

Both OTel views encode canonical trace identity, the actual operation span ID (including an invocation-view continuation), and the resolved sampled/unsampled decision. Before span creation they derive the existing deterministic logical operation ID. Producers create no span solely for an ID, reject inactive/mismatched ownership and cannot return stale metadata after failed setup. Tracer/provider/resource ownership is unchanged.

Backward compatibility is additive: existing supported core ranges and provider API version 1 remain unchanged. OTel modules do not eagerly import missing new core types. On older cores without the contract, existing plugin loading/tracing continues and the new producer returns no contribution. A coordinated capable core is required only for the new typed metadata/collector capability. Runtime type introspection remains safe in either case, and SDK-owned types are used when available.

Validation: 1,716 core tests and 267 OTel tests pass; both package type and formatter/linter checks pass, as does git diff --check. New unit/component cases cover immutable contracts, optional-hook compatibility, merge/conflict diagnostics, synchronous/error/cancellation behavior and real OTel exporters. Root/Parent/Sampled match operation contexts without extra spans or ambient mutation. Actual installed core 2.0.0 plus this OTel wheel passes 14 valid-registration, wait/resume, success/failure and constructor-correlation cases. An OTel-only layer over separately installed core 2.0.1 passes the same 14 cases and pip check, with no core package in the layer; import paths and type introspection are verified. No AWS calls were needed.

Before this can become a complete feature:

  1. Supported public client models and generated serialization for the missing fields.
  2. Backend capability rollout.
  3. Consume the hook on real invoke START, with replay and failed-checkpoint integration coverage.
  4. Deployed topology/propagation validation.

Integration prerequisite: rebase onto the coordinated minor fixes #752/#753/#754, retaining exclusivity metadata and compatible registration cleanup. Version/release coordination must preserve existing valid combinations and advertise the new capability separately; do not raise the broad core minimum merely to force rejection of old installations. Keep this PR draft while model/backend dependencies block completion. The full feature issue remains open; no unsupported wire members, serializer bypasses or new fanout/HTTP APIs are included.

This branch has not been deployed

No deployments
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.

1 participant