docs(frameworks): TanStack AI tracing (TH-8238) - #1013

Summary

New page src/pages/docs/integrations/frameworks/tanstack-ai.mdx: trace TanStack AI (@tanstack/ai) server-side chat() calls with TanStack's own otelMiddleware and a tracer provider from @traceai/fi-core. No traceAI package; the recipe file (tracing.mjs) is embedded in the page and is the same file as the runnable example in future-agi/traceAI#212 (typescript/examples/tanstack-ai).

Sections: install (with the SDK and adapter pins), environment, the recipe file, a traced route (abort wiring, bounded flush), run and check (span table, error shapes), what is captured (default vs captureContent: true), privacy (metadata only by default; error text and stack traces replaced by error.type; opt-in with redact; opaque session ids), apps that already run OpenTelemetry (new trace per chat, joinActiveTrace), how it behaves, limitations, troubleshooting, and how it differs from the Vercel AI SDK integration, the OpenAI instrumentor and the OpenInference TanStack middleware.

Tested

• @tanstack/ai 0.69.0 (npm latest, 2026-10-13) with @tanstack/ai-openai 0.30.0, @tanstack/openai-base 0.14.0, OpenTelemetry SDK 2.12.0; also the earlier set @tanstack/ai 0.64.0 / ai-openai 0.26.0 / SDK 2.11.0. @traceai/fi-core 1.0.0. Node 22.18.0 and 26.8.1.
• Real end-to-end runs against a self-hosted Future AGI (Observe UI + stored spans): a tool-calling chat, a tool that throws, an unknown model (ERROR), a chat under an app's own active span, and the content opt-in; fi_verify PASS on each project.
• Live vendor verification (2026-10-17): the same runs with a real OpenAI key on gpt-4o-mini (provider openai, response model gpt-4o-mini-2024-07-18, per-call cost computed, 404 unknown model → ERROR model_not_found). Spend about $0.0001.
• Privacy: a unique marker, a home path, the user name, the host name, an email address and all keys were absent from every stored column with the default; present only as documented with the opt-in; no stack trace in either mode. Details and trace ids in feat(examples): TanStack AI otelMiddleware recipe (TH-8238) traceAI#212 "Re-verification (2026-10-16)".

Build

docs_build.sh: BUILD_EXIT=0; audit-links: 0 broken nav links, 0 broken content links.

Navigation

src/lib/navigation.ts is not edited. Suggested nav: group Integrations → Frameworks, title "TanStack AI" (page /docs/integrations/frameworks/tanstack-ai), next to the other framework recipes.

Depends on

future-agi/traceAI#212 (head f2295cb): the page's tracing.mjs and the example the "Source" row links to. The link resolves once #212 is merged and released to main.

Limitations stated on the page

• The Tracing list shows no tokens for a TanStack trace (the list reads the root span; the recipe moves the root's sum off it so trace view, sessions, dashboards and cost count each call once).
• Input/Output panes stay empty with content on (content is in attributes).
• chat({ stream: false }) loses failed traces (0.64.0 to 0.69.0).
• Not tested: hosted api.futureagi.com, other adapters, media activities, browser and edge runtimes.

Linear: TH-8238.

🤖 Generated with Claude Code