Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

debug-logging.md

198 lines6.9 KB

1---
2title: Debug Logging
3id: debug-logging
4order: 3
5description: "Turn on structured, category-toggleable debug logging to see every chunk, middleware transform, and tool call inside TanStack AI."
6keywords:
7 - tanstack ai
8 - debug
9 - logging
10 - logger
11 - pino
12 - troubleshooting
13 - chunks
14 - middleware debugging
15---
16​
17# Debug Logging
18​
19You have a `chat()` that isn't behaving as expected — a missing chunk, a middleware that doesn't seem to fire, a tool call with wrong args. By the end of this guide, you'll have turned on debug logging and will see every chunk, middleware transform, and tool call flowing through your call.
20​
21## Turn it on
22​
23Add `debug: true` to any activity call:
24​
25```typescript
26import { chat } from "@tanstack/ai";
27import { openaiText } from "@tanstack/ai-openai";
28​
29const stream = chat({
30 adapter: openaiText("gpt-5.5"),
31 messages: [{ role: "user", content: "Hello" }],
32 debug: true,
33});
34```
35​
36Every internal event now prints to the console with a `[tanstack-ai:<category>]` prefix:
37​
38```
39[tanstack-ai:request] activity=chat provider=openai model=gpt-5.5 messages=1 tools=0 stream=true
40[tanstack-ai:agentLoop] run started
41[tanstack-ai:provider] provider=openai type=response.output_text.delta
42[tanstack-ai:output] type=TEXT_MESSAGE_CONTENT
43...
44```
45​
46## Narrow what's printed
47​
48Pass a `DebugConfig` object instead of `true`. Every unspecified category defaults to `true`, so toggle by setting specific flags to `false`:
49​
50```typescript
51import { chat } from "@tanstack/ai";
52import { openaiText } from "@tanstack/ai-openai";
53​
54chat({
55 adapter: openaiText("gpt-5.5"),
56 messages: [{ role: "user", content: "Hello" }],
57 debug: { middleware: false }, // everything except middleware
58});
59```
60​
61If you want to see ONLY a specific set of categories, set the rest to `false` explicitly. Errors default to `true` — keep them on unless you really want total silence:
62​
63```typescript
64import { chat } from "@tanstack/ai";
65import { openaiText } from "@tanstack/ai-openai";
66​
67chat({
68 adapter: openaiText("gpt-5.5"),
69 messages: [{ role: "user", content: "Hello" }],
70 debug: {
71 provider: true,
72 output: true,
73 middleware: false,
74 tools: false,
75 agentLoop: false,
76 config: false,
77 errors: true, // keep errors on — they're cheap and important
78 request: false,
79 },
80});
81```
82​
83## Pipe into your own logger
84​
85Pass a `Logger` implementation and all debug output flows through it instead of `console`:
86​
87```typescript
88import { chat, type Logger } from "@tanstack/ai";
89import { openaiText } from "@tanstack/ai-openai";
90import pino from "pino";
91import { messages } from "./server";
92​
93const pinoLogger = pino();
94const logger: Logger = {
95 debug: (msg, meta) => pinoLogger.debug(meta, msg),
96 info: (msg, meta) => pinoLogger.info(meta, msg),
97 warn: (msg, meta) => pinoLogger.warn(meta, msg),
98 error: (msg, meta) => pinoLogger.error(meta, msg),
99};
100​
101chat({
102 adapter: openaiText("gpt-5.5"),
103 messages,
104 debug: { logger }, // all categories on, piped to pino
105});
106```
107​
108The default logger is exported as `ConsoleLogger` if you want to wrap it:
109​
110```typescript
111import { ConsoleLogger } from "@tanstack/ai";
112```
113​
114### Your `Logger` is wrapped in a try/catch
115​
116If your `Logger` implementation throws — a cyclic-meta `JSON.stringify`, a transport that rejects synchronously, a typo in a bound `this` — the exception is swallowed so it never masks the real error that triggered the log call (for example, a provider SDK failure inside the chat stream). You won't see the log line, but the pipeline error still surfaces through thrown exceptions and `RUN_ERROR` chunks.
117​
118If you need to know when your own logger is failing, guard inside your implementation:
119​
120```typescript
121import { type Logger } from "@tanstack/ai";
122import pino from "pino";
123​
124const pinoLogger = pino();
125const logger: Logger = {
126 debug: (msg, meta) => {
127 try {
128 pinoLogger.debug(meta, msg);
129 } catch (err) {
130 // surface to wherever you track infra errors
131 process.stderr.write(`logger failed: ${String(err)}\n`);
132 }
133 },
134 info: (msg, meta) => pinoLogger.info(meta, msg),
135 warn: (msg, meta) => pinoLogger.warn(meta, msg),
136 error: (msg, meta) => pinoLogger.error(meta, msg),
137};
138```
139​
140## Categories reference
141​
142| Category | Logs | Applies to |
143|----------|------|------------|
144| `request` | Outgoing call to a provider (model, message count, tool count) | All activities |
145| `provider` | Every raw chunk/frame received from a provider SDK | Streaming activities (`chat`, `realtime`, and streaming `generateAudio`/`generateSpeech`/`generateTranscription`) |
146| `output` | Every chunk or result yielded to the caller | All activities |
147| `middleware` | Inputs and outputs around every middleware hook | `chat()` only |
148| `tools` | Before/after tool call execution | `chat()` only |
149| `agentLoop` | Agent-loop iterations and phase transitions | `chat()` only |
150| `config` | Config transforms returned by middleware `onConfig` hooks | `chat()` only |
151| `errors` | Every caught error anywhere in the pipeline | All activities |
152​
153## Errors are always logged
154​
155Errors flow through the logger unconditionally — even when you omit `debug`:
156​
157```typescript
158import { chat } from "@tanstack/ai";
159import { adapter } from "./server";
160​
161chat({ adapter, messages: [{ role: "user", content: "Hello" }] }); // still prints [tanstack-ai:errors] ... on failure
162```
163​
164To fully silence (including errors), set `debug: false` or `debug: { errors: false }`. Errors also always reach the caller via thrown exceptions or `RUN_ERROR` stream chunks — the logger is additive, not the only surface.
165​
166## Non-chat activities
167​
168The same `debug` option works on every activity:
169​
170```typescript
171import {
172 summarize,
173 generateImage,
174 generateSpeech,
175 generateAudio,
176 generateTranscription,
177 type Logger,
178} from "@tanstack/ai";
179import { adapter } from "./server";
180import { logger } from "./logger";
181​
182const text = "Long article to summarize...";
183const audio = new File([""], "recording.mp3", { type: "audio/mpeg" });
184​
185summarize({ adapter, text, debug: true });
186generateImage({ adapter, prompt: "a cat", debug: { logger } });
187generateSpeech({ adapter, text, debug: { request: true } });
188generateAudio({ adapter, prompt: "ambient piano", debug: true });
189generateTranscription({ adapter, audio, debug: { provider: true } });
190```
191​
192When streaming any of these (`generateAudio`, `generateSpeech`, `generateTranscription` with `stream: true`), the `provider` category emits the raw SDK chunks and `output` emits the AG-UI-shaped chunks yielded to the caller — useful when a media pipeline looks stuck or the bytes arriving don't match what you expected.
193​
194The chat-only categories (`middleware`, `tools`, `agentLoop`, `config`) simply never fire for these activities because those concepts don't exist in their pipelines.
195​
196## Related
197​
198If you're building middleware and want to see chunks flow through it, `debug: { middleware: true }` is faster than writing a logging middleware. See [Middleware](./middleware) for writing your own middleware.