Skip to content

feat(fi-core): maintain native TanStack AI tracing options - #441

Open
nik13 wants to merge 2 commits into
devfrom
fix/tanstack-native-shared-adapter
Open

nik13 wants to merge 2 commits into
devfrom
fix/tanstack-native-shared-adapter

Conversation

@nik13

@nik13 nik13 commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Our TanStack AI guide already uses the right mechanism, TanStack's own otelMiddleware. But it asks customers to copy a roughly 350-line tracing.mjs recipe that also deletes keys from the SDK span's private attributes object. That only works on a pinned OTel SDK, and it fails with any tracer that exposes only the public Span API. This PR moves the recipe's logic into maintained code in @traceai/fi-core and stops mutating SDK internals.

  • @traceai/fi-core/tanstack subpath: tanStackOtelOptions(tracer, options) returns options for TanStack's public otelMiddleware(options). TanStack remains the only span source, so there is no second instrumentation and no duplicate spans. The returned tracer is a public-API facade:

    • error text and stack traces stay hidden by default;
    • with captureContent: true, error text goes through a fail-closed redact.

    The returned hooks add Future AGI span kinds, gen_ai.provider.name and an opt-in session.id from threadId. joinActiveTrace keeps the recipe's new-trace default.

  • Root usage counted once without private mutation: TanStack sums every model call's usage onto the chat span. The hooks reserve a marker attribute when the chat span starts and set it when the span ends. normalizeTanStackSpan then moves the summed usage to tanstack.ai.root_usage.* in the Future AGI export view only. Other exporters on the same provider receive TanStack's spans with the enrichment attributes (span kind, provider, opt-in session and the marker); only the Future AGI export view moves root usage. The move is all-or-nothing, the same as the recipe: the root keeps its usage when no model-call span reported any.

  • Shared export layer: TransformingSpanExporter and a spanTransform option on register() and the provider (main entry point). A failing transform drops the batch rather than exporting untransformed data. Apps with their own OTel SDK compose it as new TransformingSpanExporter(exporter, normalizeTanStackSpan).

  • registerTanStackTracing(): an isolated OBSERVE provider that never replaces the global provider. It has no project-name fallback, so a missing FI_PROJECT_NAME throws, as register() does. It leaves out batch on purpose: on current dev, register({ batch: true }) relies on processor fields that OTel 2 removed. fix(fi-core): restore OpenTelemetry 2 provider lifecycle #365 fixes that.

  • flushTraces and shutdownTraces are bounded and never throw, matching the recipe's behaviour.

Why a subpath on fi-core and not a new @traceai/tanstack package: @tanstack/ai is ESM-only, and the adapter needs no runtime dependency on it, because customers call TanStack's otelMiddleware themselves. Shipping it inside the one package the page already installs keeps the install surface the same. It is not re-exported from index.ts.

Arize packages an OpenInference TanStack middleware, and Langfuse recommends that maintained middleware. Here the equivalent maintained route sits over TanStack's own middleware. No vendor code was copied.

Reproduction

At dev d6a9966dd, run the published recipe (typescript/examples/tanstack-ai/src/tracing.mjs, pinned installs) with a tracer that exposes only the public Span methods. One model call with 11 input tokens exports 22 input tokens across the trace: the root keeps TanStack's sum because span.attributes is not reachable. The committed test also has a negative control: a bare otelMiddleware({ tracer }) gives 44 for two calls of 11.

Verification

All runtime tests ran with outbound network denied except loopback (macOS sandbox-exec). No vendor or model API was called and no real credentials were used. Fixtures are clean npm installs of the packed fi-core and fi-semantic-conventions tarballs, run on Node 22.23.4 (the CI version) and 26.8.1:

Fixture @tanstack/ai / adapter OTel SDK / exporter Result
floor 0.69.0 / ai-openai 0.30.0 2.0.1 / 0.202.0 24/24
current 1.0.1 / ai-openai 1.0.1 2.12.0 / 0.223.0 24/24

Coverage:

  • Token counting with a public-only tracer: simple and batch processors, one and two model calls, every gen_ai.usage.* key including cost, cache and reasoning.
  • The fallback when only the root reports usage, including zero usage.
  • 30 concurrent runs sharing one middleware.
  • Isolated and joined parent traces.
  • Model and tool errors with content off and on; redactor failures; all startActiveSpan overloads.
  • Immutable, idempotent normalization, including frozen spans; transform-failure behaviour; bounded flush and shutdown.
  • ESM and CJS entry points.
  • Real streamed chat() through the OpenAI adapter against a loopback fake model, for tools, tool error, model error, abort mid-stream and content opt-in. Each case asserts on the actual OTLP/HTTP request: /tracer/v1/traces, auth headers, project_name, trace and parent IDs, session.id, no duplicate spans, tokens counted once, no private text and no exception.stacktrace.

Mutation checks against the packed current fixture: making the normalizer an identity function fails 11 tests, and removing the tracer facade fails 14.

The existing fi-core Jest suite passes 142/142 and the strict CJS, ESM and ESNext builds succeed. git diff --check is clean. pnpm lint could not run because ESLint is not installed in the workspace.

New CI: .github/workflows/fi-core-tanstack.yml builds and packs the core and installs the floor and current fixtures. It then runs this suite and the Jest suite inside a loopback-only Linux network namespace, mirroring #416.

Compatibility and release

  • The change is additive: existing register() and provider behaviour is unchanged when spanTransform is unset.
  • The example recipe typescript/examples/tanstack-ai/ is left unchanged. It works with released packages and is what the live docs page points at. Customers who copied it keep working on their pinned versions.
  • Once this ships, a docs-site follow-up replaces the copied recipe on the page with otelMiddleware(tanStackOtelOptions(tracer)) and retires the example. No docs PR is opened before the package is on npm.
  • Overlap: the otel.ts change (about 7 additive lines) touches the file that fix(fi-core): restore OpenTelemetry 2 provider lifecycle #365 rewrites. The rebase is mechanical: pass spanTransform through to the exporter that fix(fi-core): restore OpenTelemetry 2 provider lifecycle #365 builds. There is no functional overlap with fix(fi-core): redact native GenAI message payloads #416, which covers GenAI message masking.
  • This is a feat commit; release-please owns the version and changelog. There is no manual version bump, tag or publish.

E2E coverage

Not applicable: traceAI has no product e2e/ harness. The OTLP wire is covered offline as described above. No Cloud or UI execution is claimed.

🤖 Generated with Claude Code

nik13 and others added 2 commits October 31, 2026 10:41
Add a @traceai/fi-core/tanstack subpath that supplies options for TanStack
AI's own otelMiddleware instead of asking customers to copy a recipe file.

- TanStack stays the only span source. tanStackOtelOptions() returns a
  public-API tracer facade (error text and stack traces hidden by default,
  content and error text only through captureContent with fail-closed
  redaction) plus span-kind, provider and opt-in session hooks.
- Root usage is no longer moved by deleting SDK span attributes. The hooks
  mark the chat span, and normalizeTanStackSpan() moves TanStack's summed
  root usage to tanstack.ai.root_usage.* only in the Future AGI export view.
  Other exporters still see the original span.
- Add TransformingSpanExporter and a register()/provider spanTransform option
  so the same normalization composes with an existing OpenTelemetry SDK.
- registerTanStackTracing() registers an isolated OBSERVE provider that never
  replaces the global provider.

Tests run against packed builds at @tanstack/ai 0.69.0 with OTel SDK 2.0.1
and @tanstack/ai 1.0.1 with SDK 2.12.0, including real streamed chats and
OTLP wire checks over loopback.

Co-Authored-By: Claude Code <noreply@anthropic.com>
flushTraces() unrefs its timer so a pending flush never holds a process
open. Under Node 22's test runner, waiting on a collector that never answers
then left nothing on the event loop and cancelled the remaining tests. Keep
an interval alive for that one test, and assert the bound is honoured.

Also clarify in the README that other exporters receive the enrichment
attributes; only the Future AGI export view moves root usage.

Co-Authored-By: Claude Code <noreply@anthropic.com>

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