Skip to content

fix(fireworks): trace TypeScript Fireworks clients through the shared OpenAI route - #509

Merged
nik13 merged 2 commits into
devfrom
fix/fireworks-typescript-shared-route
Nov 1, 2026
Merged

nik13 merged 2 commits into
devfrom
fix/fireworks-typescript-shared-route

Conversation

@nik13

@nik13 nik13 commented Nov 1, 2026

Copy link
Copy Markdown
Contributor

Summary

@traceai/fireworks (TypeScript) exported no spans on any supported OpenAI SDK. It wrapped OpenAI.prototype.chat.completions and similar paths, which don't exist (the SDK creates resources per client instance), but isPatched() still returned true. This PR sends Fireworks through the shared OpenAI-compatible route, matching the Python change in #367.

  • @traceai/openai: the exact host api.fireworks.ai now maps to gen_ai.provider.name=fireworks. This matches python/frameworks/openai/traceai_openai/_providers.py. Look-alike hosts, a bare fireworks.ai and custom proxies keep the existing openai fallback.
  • @traceai/fireworks: FireworksInstrumentation is now a deprecated subclass of OpenAIInstrumentation. It keeps the same public entry points (FireworksInstrumentation, isPatched, VERSION, constructor options, setTracerProvider, manuallyInstrument, enable/disable). Constructing it emits one DeprecationWarning (TRACEAI_FIREWORKS_DEPRECATED) per process. A delegate works here, unlike Python, because the shared package already supports the Fireworks package's SDK floor (4.0.0) and goes up to 7.x. The 750-line copy of the instrumentation goes away, and the package now depends only on @traceai/openai.
  • Patch ownership (@traceai/openai): only the instance that applied a patch may remove it. Before this fix, if two instrumentors shared the SDK (for example FireworksInstrumentation plus OpenAIInstrumentation during migration, or two OpenAIInstrumentations), disabling the one that didn't patch unwrapped the SDK. Tracing then stopped silently, because the CommonJS require hook still asks every instance to unpatch. The fix is a per-instance WeakSet plus a guard in unpatch (3 lines).

Behavior changes for existing @traceai/fireworks users

  • Every OpenAI SDK client in the process is traced, not only Fireworks clients. Each span's provider comes from that client's API host.
  • Span names are OpenAI Chat Completions / OpenAI Completions / OpenAI Embeddings. The instrumentation scope is the shared instrumentor's (@traceai/fi-instrumentation-openai). instrumentationName is no longer @traceai/fireworks. Before this PR the package produced no spans at all.
  • The openai peer range goes from >=4.0.0 (optional) to ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0, the same as @traceai/openai. This is not a breaking change: no version in the old range was ever actually traced.
  • When both instrumentors are enabled, each request produces one span. The instrumentor that patched first supplies the tracer provider and traceConfig.

Known limits (documented, not changed):

  • Disabling the instrumentor that owns the patch stops tracing even if the other is still enabled. The README says to disable both.
  • The ownership guard only applies when both instrumentors resolve to the same @traceai/openai copy. An app that pins an older @traceai/openai next to the new @traceai/fireworks gets a nested copy without the guard. The migration step "remove @traceai/fireworks" avoids this.

Reproduction (fails before the fix)

  • Earlier audit regression across 84 cases on SDK 4.0.0, 4.77.0, 5.23.2 and 7.47.0: Fireworks-only instrumentation exported zero spans for chat, completions, embeddings, streams and HTTP errors.
  • New tests on the current dev base 979c2716:
    • provider.test.ts failed for api.fireworks.ai.
    • The new Fireworks Jest suite: 15 of 16 failed. Zero spans, mixed-client attribution wrong, isPatched() stayed true after disable(), no deprecation warning.
    • The new patchOwnership.test.ts failed: after the non-owner was disabled, isPatched() was false and no span was exported.
    • The clean-consumer contract both=true failed on 4.0.0 and 7.47.0 with real require hooks, logging No original to unwrap to.

Validation (outbound network denied, loopback only)

  • @traceai/openai full Jest suite: 185 passed, 2 skipped (both skipped before this PR too), 15 snapshots.
  • @traceai/fireworks Jest suite: 16/16 on the locked SDK and on OpenAI 4.0.0 and 7.47.0 (OPENAI_TEST_MODULE). Shared provider, wire and ownership tests: 68/68 on 4.0.0, 74/74 on 7.47.0.
  • Packed tarballs (@traceai/openai + @traceai/fireworks) installed in a clean consumer, exporting real OTLP/JSON to a loopback receiver, on OpenAI 4.0.0, 5.23.2, 6.0.0 and 7.47.0. Each version ran four modes: automatic CommonJS hooks, explicit manuallyInstrument, each with and without OpenAIInstrumentation also enabled. 11–12 passed per run, 0 failures. Covered:
    • exactly one fireworks span for chat, completions, embeddings, chat and completion streams, and HTTP errors;
    • an api.openai.com client in the same process stays openai;
    • disabling the non-owner keeps tracing, and disabling both stops it;
    • hidden content, error text and credentials do not reach the wire;
    • exactly one deprecation warning.
  • The ESM build loads and instruments the SDK. The consumer d.ts typechecks under --strict for ESM and CJS.
  • The README recipe runs unchanged against the packed packages through register() and loopback OTLP (5.23.2, 7.47.0), and typechecks. It is skipped on 4.0.0 because that SDK's node-fetch shim ignores the recipe's synthetic global fetch.
  • pnpm install --frozen-lockfile --ignore-scripts, release_plan.py --check, bootstrap_audit.py --check and 69 release unit tests passed. The lockfile change is confined to the traceai_fireworks importer and was hand-edited, not re-resolved.

New CI: .github/workflows/fireworks-typescript-tests.yml runs the tarball contracts, README, ESM and Jest steps on 4.0.0, 5.23.2, 6.0.0 and 7.47.0 in a loopback-only network namespace. openai-sdk-contracts.yml now also runs patchOwnership.test.ts across its matrix.

Release

Both packages already have release-please config and manifest entries, and this PR has no version or changelog edits. The npm release runs in dependency order, so @traceai/openai publishes before @traceai/fireworks. workspace:^ becomes the released @traceai/openai version range. The fix reaches users only once both packages are on npm. A customer docs page is held until then; no docs PR has been opened.

Related PRs

🤖 Generated with Claude Code

nik13 and others added 2 commits November 1, 2026 15:04
… OpenAI route

FireworksInstrumentation wrapped nonexistent OpenAI.prototype resources and
exported no spans on any supported SDK while reporting isPatched() true.

- @traceai/openai attributes the exact api.fireworks.ai host to fireworks.
- FireworksInstrumentation is now a deprecated delegate to
  OpenAIInstrumentation: one DeprecationWarning per process, same public
  entry points, OpenAI SDK 4.x-7.x.
- Only the instrumentor that applied a patch removes it, so disabling a
  second instrumentor sharing the SDK no longer silently stops tracing.
- Network-isolated contracts on packed tarballs for SDK 4.0.0, 5.23.2,
  6.0.0 and 7.47.0, plus a migration README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ared route

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nik13
nik13 merged commit e746b14 into dev Nov 1, 2026
74 checks passed
@nik13
nik13 deleted the fix/fireworks-typescript-shared-route branch November 1, 2026 23:24
@nik13 nik13 mentioned this pull request Nov 5, 2026
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