Skip to content

Commit c6001eb

Browse files
committed
fix(examples): bound the TanStack AI trace flush on the request path
flushTraces() awaited forceFlush() with no bound. A collector that accepts the connection and never answers held the route until the OTLP/HTTP exporter's 10 s timeout (otlp-exporter-base 0.202.0). flushTraces(tracerProvider, { timeoutMs = FLUSH_TIMEOUT_MS = 2000 }) races the flush against an unref'd timer, logs "[futureagi] span export still pending after 2000 ms; not waiting", lets the export finish in the background, and still never throws. The README and the doc comment say the per-request flush is for serverless routes and that a long-lived server should not await a flush on the request path (the SimpleSpanProcessor already exports each span as it ends) and should call shutdownTraces() at exit. Test first: tests/timed_route.mjs prints the route's duration, and the new contract test points the exporter at a socket that accepts and never replies. It failed with routeMs 13504 and now passes (routeMs 2157 in a manual run). The refused-port test still passes. approved: Nikhil 2026-10-03 blanket Refs: TH-8238
1 parent 48e2af0 commit c6001eb

4 files changed

Lines changed: 93 additions & 7 deletions

File tree

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

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -116,8 +116,14 @@ into a browser bundle.
116116
`register({ batch: true })` does not attach its batch processor with
117117
`@traceai/fi-core` 1.0.0 on `@opentelemetry/sdk-trace(-base)` 2.11.0 (the
118118
versions this example installs), so it is not passed.
119-
- `forceFlush()` rejects when the collector is unreachable. `flushTraces()`
120-
logs that and returns, so `chat()` and the route still succeed.
119+
- `forceFlush()` rejects when the collector is unreachable and can wait for
120+
the exporter's 10 s timeout when the collector accepts but does not answer.
121+
`flushTraces()` logs either case, waits at most 2 s (`FLUSH_TIMEOUT_MS`),
122+
and never throws, so `chat()` and the route still answer.
123+
- The per-request flush is for serverless routes, where the process can be
124+
frozen after the response. In a long-lived server, do not await a flush on
125+
the request path: the default `SimpleSpanProcessor` exports each span when
126+
it ends. Call `shutdownTraces()` when the process stops.
121127
- Do not also register the OpenInference TanStack middleware or wrap `chat()`.
122128
Either duplicates spans.
123129

‎typescript/examples/tanstack-ai/src/tracing.mjs‎

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,15 +32,40 @@ function describe(error) {
3232
return errors.map((e) => e?.message ?? String(e)).join("; ");
3333
}
3434

35+
/** How long the route waits for span export before it answers anyway. */
36+
export const FLUSH_TIMEOUT_MS = 2000;
37+
3538
/**
36-
* Wait for in-flight span exports. Call it in the route's finally. An
37-
* unreachable collector is logged here and never fails the request.
39+
* Wait for in-flight span exports, at most `timeoutMs`. Call it in the
40+
* route's finally. Never throws: an unreachable collector is logged, and a
41+
* collector that does not answer within the bound is logged and left to
42+
* finish in the background (OTLP/HTTP gives up after its own 10 s timeout).
43+
*
44+
* This is for serverless routes, where the process may be frozen once the
45+
* response is sent. In a long-lived server, do not await a flush on the
46+
* request path at all: the SimpleSpanProcessor already exports each span when
47+
* it ends, so call shutdownTraces() when the process stops instead.
3848
*/
39-
export async function flushTraces(tracerProvider) {
49+
export async function flushTraces(tracerProvider, { timeoutMs = FLUSH_TIMEOUT_MS } = {}) {
50+
let timer;
51+
const timedOut = new Promise((resolve) => {
52+
timer = setTimeout(() => resolve(true), timeoutMs);
53+
timer.unref?.();
54+
});
4055
try {
41-
await tracerProvider.forceFlush();
56+
const flushed = tracerProvider.forceFlush().then(() => false);
57+
if (await Promise.race([flushed, timedOut])) {
58+
console.error(
59+
`[futureagi] span export still pending after ${timeoutMs} ms; not waiting`,
60+
);
61+
flushed.catch((error) => {
62+
console.error(`[futureagi] span export failed: ${describe(error)}`);
63+
});
64+
}
4265
} catch (error) {
4366
console.error(`[futureagi] span export failed: ${describe(error)}`);
67+
} finally {
68+
clearTimeout(timer);
4469
}
4570
}
4671

‎typescript/examples/tanstack-ai/tests/test_tanstack_ai_contract.py‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,17 @@
1111

1212
from __future__ import annotations
1313

14+
import contextlib
1415
import json
1516
import os
17+
import re
1618
import shutil
1719
import socket
1820
import sys
21+
import threading
1922
from pathlib import Path
2023
from types import SimpleNamespace
21-
from typing import Any
24+
from typing import Any, Iterator
2225

2326
import pytest
2427

@@ -291,6 +294,44 @@ def test_unreachable_collector_does_not_fail_chat():
291294
assert "[futureagi] span export failed" in result.stderr.decode()
292295

293296

297+
@contextlib.contextmanager
298+
def _silent_collector() -> Iterator[str]:
299+
"""A collector that accepts connections and never answers."""
300+
server = socket.socket()
301+
server.bind(("127.0.0.1", 0))
302+
server.listen(16)
303+
held: list[socket.socket] = []
304+
305+
def accept() -> None:
306+
while True:
307+
try:
308+
connection, _ = server.accept()
309+
except OSError:
310+
return
311+
held.append(connection)
312+
313+
threading.Thread(target=accept, daemon=True).start()
314+
try:
315+
yield "http://127.0.0.1:{0}".format(server.getsockname()[1])
316+
finally:
317+
server.close()
318+
for connection in held:
319+
connection.close()
320+
321+
322+
def test_silent_collector_does_not_hold_the_response():
323+
"""The route's flush is bounded, so a collector that never answers costs
324+
the request at most the flush bound, not the exporter's 10 s timeout."""
325+
with _silent_collector() as fi_base_url, FakeOpenAI(CITY, ANSWER) as fake:
326+
result = _node(TESTS / "timed_route.mjs", fi_base_url, fake)
327+
stdout = result.stdout.decode()
328+
assert result.returncode == 0, result.stderr.decode()
329+
assert ANSWER in stdout
330+
route_ms = int(re.search(r"routeMs=(\d+)", stdout).group(1))
331+
assert route_ms < 3000, route_ms
332+
assert "[futureagi] span export still pending" in result.stderr.decode()
333+
334+
294335
def test_failed_model_call_exports_error_spans():
295336
"""A model call that fails still ends and exports the root and LLM spans.
296337
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
// Test fixture: run the route once and print how long it took, so the
2+
// contract test can check that a slow collector does not hold the response.
3+
import { chatRoute } from "../src/chat.mjs";
4+
import { registerFutureAgiTracing, shutdownTraces } from "../src/tracing.mjs";
5+
6+
const tracerProvider = registerFutureAgiTracing();
7+
const started = performance.now();
8+
try {
9+
const text = await chatRoute(process.argv[2], tracerProvider);
10+
console.log(`routeMs=${Math.round(performance.now() - started)}`);
11+
console.log(text);
12+
} finally {
13+
await shutdownTraces(tracerProvider);
14+
}

0 commit comments

Comments
 (0)