Skip to content

Commit d871239

Browse files
committed
docs(examples): state where TanStack AI spans can still be lost
Installed review N2: the README gave the 2 s flush bound but not its consequences. - Serverless: flushTraces() stops waiting at the bound; it does not stop the export (tracing.mjs flushTraces leaves `flushed` running). Spans still pending then are lost if the runtime freezes or exits after the response. The `timeoutMs` option was not documented. - Long-lived servers: register()'s default SimpleSpanProcessor (@traceai/fi-core 1.0.0 otel.js 356-358) exports each span in its own OTLP request. The OTLP/HTTP exporter (otlp-exporter-base 0.202.0 shared-configuration.js 54-55) allows 30 exports in flight with a 10 s timeout each and rejects the rest with "Concurrent export limit reached" (otlp-export-delegate.js 43-46), so with a slow collector spans drop from about 8 concurrent chats of 4 spans. The Notes section now says both and documents flushTraces(tracerProvider, { timeoutMs }). Documentation only. The slow-collector concurrency case is described, not tested (no fixture for 10 concurrent routes against a delaying collector). approved: Nikhil 2026-10-03 blanket Refs: TH-8238
1 parent 9bf9cf8 commit d871239

1 file changed

Lines changed: 13 additions & 4 deletions

File tree

‎typescript/examples/tanstack-ai/README.md‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -194,11 +194,20 @@ into a browser bundle.
194194
- `forceFlush()` rejects when the collector is unreachable and can wait for
195195
the exporter's 10 s timeout when the collector accepts but does not answer.
196196
`flushTraces()` logs either case, waits at most 2 s (`FLUSH_TIMEOUT_MS`),
197-
and never throws, so `chat()` and the route still answer.
197+
and never throws, so `chat()` and the route still answer. Pass
198+
`flushTraces(tracerProvider, { timeoutMs })` for a different bound.
198199
- The per-request flush is for serverless routes, where the process can be
199-
frozen after the response. In a long-lived server, do not await a flush on
200-
the request path: the default `SimpleSpanProcessor` exports each span when
201-
it ends. Call `shutdownTraces()` when the process stops.
200+
frozen after the response. The bound stops the wait, not the export: spans
201+
still pending when it runs out keep exporting in the background, and are
202+
lost if the runtime then freezes or exits. Raise `timeoutMs` if your
203+
platform allows the time.
204+
- In a long-lived server, do not await a flush on the request path: the
205+
default `SimpleSpanProcessor` exports each span when it ends, in its own
206+
OTLP request (4 requests for a chat with one tool call). The OTLP/HTTP
207+
exporter allows 30 exports in flight and waits up to 10 s for each; with a
208+
slow collector, spans past that limit are dropped with "Concurrent export
209+
limit reached", from about 8 concurrent chats of 4 spans. Call
210+
`shutdownTraces()` when the process stops.
202211
- Do not also register the OpenInference TanStack middleware or wrap `chat()`.
203212
Either duplicates spans.
204213

0 commit comments

Comments
 (0)