Skip to content

docs: simplify and update OpenTelemetry guide - #302

Merged
zhongkechen merged 32 commits into
mainfrom
docs/simplify-opentelemetry
Nov 10, 2026
Merged

zhongkechen merged 32 commits into
mainfrom
docs/simplify-opentelemetry

Conversation

@zhongkechen

@zhongkechen zhongkechen commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

The OpenTelemetry guide now uses the unified factories: TypeScript createOtelPluginFactory, Python create_otel_plugin_factory, and Java OtelPlugin.factory. Execution view is the default, with explicit invocation selection. The handler examples and Java's dynamic-loading example use these APIs; Go, Rust, and C# remain explicitly unsupported for this integration.

  • Set installation minimums to TypeScript core 3.0.0 / OTel 2.1.0, Python OTel 2.1.0 with compatible core 3.x, and matching Java SDK/plugin versions starting at 3.1.0. Replace release-prerequisite history with published version requirements.
  • Preserve the view comparison and both span hierarchy diagrams, including continuation links and export timing.
  • Keep ADOT/X-Ray setup on Active and use PassThrough for community-layer OTLP export, explaining upstream sampling, propagation, native X-Ray parents, and provider ownership. Link to optional Collector configuration without duplicating its setup guide.
  • Put aliases, duplicate-registration behavior, and language-specific troubleshooting inside language tabs. Remove unsupported W3C client-context extractor references.
  • Restore copyable npm and Maven exporter installation snippets and show the Python invocation factory call with an application-owned provider. The Java exporter example uses OpenTelemetry 1.67.0 to match plugin 3.1.0.
  • Describe Python 2.1.0 error events and its cached-parent replay limitation directly. Clarify optional span attributes and TypeScript's newly observed external completion updates.
  • Add working TypeScript, Python, and Java log-correlation examples with sample output. Show the Powertools adapter, Python formatter defaults, and Logback MDC layout, including Java 3.1.0 execution-view differences between handler and step logs. Align the existing Powertools examples and logging guide.
  • Scope sampling rules to the documented versions and explicitly note that future releases may change sampling behavior.

Partially addresses #295 and #297. Keep both issues open: configured-sampler semantics are not implemented in the documented versions, and complete caller-to-OTLP validation remains outstanding. The supported-sampling-modes anchor is preserved for the coordinated README updates in aws/aws-durable-execution-sdk-js#1132, aws/aws-durable-execution-sdk-java#852, and aws/aws-durable-execution-sdk-python#885.

Validation:

  • Zensical 0.0.40 clean build, Markdown formatting, spelling, hidden-character checks, all 846 example references, and git diff --check pass.
  • The setup and logging snippets render correctly; all 1,203 local links and fragments across the OpenTelemetry and logging pages resolve.
  • The Java provider example compiles with javac --release 17 -Xlint:all against published core/plugin 3.1.0 and OpenTelemetry 1.67.0.
  • The Python invocation factory smoke test passes against published plugin 2.1.0 and core 3.0.2, preserves the supplied provider, and exports the expected Invocation hierarchy and Workflow links through an in-memory exporter with network connections blocked.
  • Factory and dependency compatibility were checked against the published TypeScript OTel 2.1.0 release and the Python/Java package metadata.
  • All three changed TypeScript examples compile with strict checking. The new handler runs against core 3.0.0 / OTel 2.1.0 / Powertools 2.36.0, with logged IDs matching the exported Workflow span.
  • The Python logging example runs twice against core 3.0.2 / OTel 2.1.0; logged IDs match Invocation spans, existing handlers and filters are preserved, and initialization and post-invocation logs use safe defaults. The TypeScript and Python logging smoke checks use in-memory exporters without service calls.
  • The Java logging example compiles and runs on JDK 17 against SDK/plugin/testing 3.1.0, OpenTelemetry 1.67.0, and Logback 1.6.6. The step log matches its exported attempt span; initialization and post-invocation logs use placeholders, with no MDC leak. The test uses an in-memory exporter without service calls.

Deployed Lambda/ADOT and external backend tests were not run; this change does not establish new backend qualification.

@zhongkechen
zhongkechen marked this pull request as ready for review November 3, 2026 19:56
@zhongkechen
zhongkechen deployed to ai-pr-review-runtime November 3, 2026 19:56 — with GitHub Actions Active
Add TypeScript and Python examples that display the trace fields enabled
by default. Use the Powertools adapter for per-call enrichment and safe
formatter defaults for Python logs outside an invocation.

Align the existing Powertools examples and logging guide with the
adapter so they preserve durable metadata and plugin fields.
Show the Logback dependency, resource configuration, and log output for
initialization, handler code, and a step. Document the execution-view
MDC behavior verified with SDK/plugin 3.1.0, including missing fields
outside step scopes and placeholder values before an invocation.
@zhongkechen
zhongkechen merged commit 6bb10d8 into main Nov 10, 2026
7 of 9 checks passed
@zhongkechen
zhongkechen deleted the docs/simplify-opentelemetry branch November 10, 2026 21:43

This branch had an error being deployed

1 failed deployment
ai-pr-review-runtime — e1091526 Deployed Nov 10, 2026 by zhongkechen via ai-pr-review / Claude review / Generate Claude review #211
ai-pr-review — 0a7966bd Deployed Nov 3, 2026 by zhongkechen via ai-pr-review / Approve AI PR review #167
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.

2 participants