Skip to content

fix(anthropic): leave native TypeScript SDK tracing unpatched - #331

Merged
nik13 merged 2 commits into
devfrom
fix/anthropic-typescript-native-boundary
Nov 1, 2026
Merged

nik13 merged 2 commits into
devfrom
fix/anthropic-typescript-native-boundary

Conversation

@nik13

@nik13 nik13 commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Keep @traceai/anthropic for its legacy SDK peer dependency, but do not monkeypatch an SDK that already exposes native OpenTelemetry. This is a containment fix, not a declaration that native spans are fully qualified for Future AGI onboarding.

  • Detect the SDK's public openTelemetry capability without invoking its instance getter; include inherited constructors and module namespaces.
  • Leave native Messages.create untouched, preserving APIPromise.withResponse(), asResponse(), SDK-owned streams, cancellation, and typed errors. Honor explicit native tracing disablement rather than silently replacing it with legacy tracing.
  • Warn that this instrumentor's traceConfig / FI_HIDE_* controls do not govern native spans.
  • Fix the pre-existing legacy Quick Start for native ESM: explicitly instrument the imported SDK; keep CommonJS automatic-plus-manual setup idempotent.
  • Preserve the legacy entry point, peer dependency, and automatic >=0.20.0 <1 instrumentation gate. No version bump, changelog change, package deletion, or release.

Reproduction

On base 8600a66c1a692f44a9f937640bb4c3ecbd42c98d, with real @anthropic-ai/sdk@1.3.0 and a synthetic fetch:

Setup Spans withResponse() retained
Native SDK 1 Yes
Manual legacy instrumentation + native SDK 2 No
Manual legacy instrumentation + native telemetry disabled 1 No

The new real-SDK contract fails against the original build at native SDK must not be monkeypatched, and passes with this fix.

Legacy README regression

The executable Quick Start test reads the actual README code block and runs it in fresh native ESM and compiled CommonJS processes with real SDK 0.27.3, a loopback provider, and a loopback OTLP receiver. Before the documentation fix, ESM produced one request and zero spans (test fails); CommonJS produced one request and one span. After the fix, both produce one request and exactly one span, with model, token usage, and fi.span.kind checked on the wire. The CommonJS case also guards against duplicate wrapping. This defect predates the native-boundary change.

Validation

All local tests ran under macOS sandbox-exec, denying outbound networking except localhost. No vendor/backend calls and no real credentials.

  • CJS, ESM and ESNext builds passed; workspace lockfile unchanged.
  • Unit tests: 56 passed; 3 pre-existing placeholder tests skipped.
  • Real SDK 1.3.0: nine synthetic requests covering await, withResponse, unread raw asResponse, streaming withResponse, stream helper, early cancellation, typed API error, telemetry disabled, and instrumentor disablement.
  • Real SDKs 0.20.0 and 0.27.3: legacy request, model/token attributes and exactly one OTLP span preserved.
  • Local OTLP/HTTP receiver verifies span counts on the wire, including zero spans for explicit native opt-out. Metadata-only success cases omit synthetic input/output canaries; the synthetic API-error detail was also absent from the native wire payload.
  • Added CI builds, unit tests, the same real-SDK matrix, and the executable README ESM/CommonJS contract in a loopback-only Linux network namespace.
  • Release hygiene: release_plan.py --check, bootstrap_audit.py --check, all 51 Python release unittests, and real release-please 17.6.0 strategy tests passed. No release metadata changed.

Remaining migration work

Do not delete the legacy package or widen automatic instrumentation support as part of this fix. Native spans still lack fi.span.kind; Future AGI backend/UI classification and complete native-vs-FI privacy semantics are not qualified here. The website's modern-SDK onboarding switch is held until that work is complete. This patch does not repair pre-existing legacy-only promise/stream implementation issues.

Overlap check

The existing Anthropic PRs concern Python. PR #310 is already merged and touches only Python; this change touches only TypeScript and its dedicated CI.

🤖 Generated with Claude Code

nik13 and others added 2 commits October 31, 2026 05:02
Keep legacy SDK tracing and the automatic version gate unchanged. Avoid duplicate spans and APIPromise/stream contract breakage when manual instrumentation is used with a native-OTel SDK. Warn that legacy traceConfig does not govern native spans.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Explicitly instrument the imported legacy SDK so native ESM emits spans. Execute the README in fresh ESM and CommonJS processes against loopback provider and OTLP endpoints in CI, checking exactly one span and its model and token attributes.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@nik13
nik13 merged commit 68bf525 into dev Nov 1, 2026
15 of 22 checks passed
@nik13
nik13 deleted the fix/anthropic-typescript-native-boundary branch November 1, 2026 03:10
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