Tracing
Tracing groups the Gateway requests that make up one logical run (an agent loop, a chain, a batch pipeline) into a single trace you can view as a tree. Use it when one user action fans out into several LLM calls and you want to see the whole run in one place: what ran, in what order, what it cost, and where the time went.
Your traffic already flows through Gateway, so there is nothing to install. Add one HTTP header to calls you already make and the requests become spans of a trace. Because tracing is header-based, it works identically on /v1/responses, chat completions, and every SDK-compatible surface, including the OpenAI SDK, the Anthropic SDK, and LangChain pointed at a Gateway base_url.
Trace rollups use the same pipeline that bills you, so the cost you see per trace is the amount you were charged, not an estimate from public price tables.
Trace headers
Four request headers control tracing. Only X-Merge-Trace-Id is required; the rest refine the shape of the trace.
Header values can be up to 128 characters (64 for X-Merge-Span-Name) from the set A-Z a-z 0-9 . _ : -. An invalid value never fails the request: Gateway drops it silently and the request proceeds untraced, so a malformed ID in your header logic costs you a trace, not an outage.
Use a fresh trace ID for every run, for example run- plus a UUID. Reusing a trace ID across unrelated runs merges them into one trace. A trace groups requests made within roughly 24 hours; longer-lived groupings belong in a thread.
Trace your first run
Generate one trace ID per run and send it on every request in the run. Span names are optional but make the tree much easier to read.
A request that carries X-Merge-Trace-Id with no parent header becomes a root span, so a single traced call is the trivial one-span trace. Requests without the header are untouched: they appear in Logs as before with no trace fields.
Nest spans under a parent
By default every traced request sits at the root of its trace, which is often all you need. To build a deeper tree, pass an earlier request’s ID as X-Merge-Parent-Span-Id.
Every Gateway response includes an X-Request-ID response header identifying that request. Capture it and pass it as the parent on follow-up calls:
If reading response headers is awkward in your setup, supply your own request ID up front: send X-Request-ID with a UUID you generated on the parent request, then reference that same value as X-Merge-Parent-Span-Id on the children.
Gateway does not verify parent references at write time. A span whose parent never arrives still renders in the trace, attached at the root level.
Automatic child spans
Some Gateway features fan one request out into several provider calls. Those internal calls become child spans automatically, with no instrumentation on your side. A traced Fusion request, for example, shows each panel model’s answer and the judge call as children of your request, so you can see what each panel member cost and how long the judge took.
Traces versus threads
Traces and threads answer different questions, and most confusion with the header contract comes from mixing them up. A trace is one run: a single agent loop, chain invocation, or pipeline execution, finished within a day. A thread is the long-lived conversation those runs belong to: a support ticket, a chat session, a user’s ongoing interaction over days.
A support agent shows the shape: every time the agent processes a new customer message, mint a fresh trace ID for that turn’s work, and send the same thread ID for the life of the ticket. Filtering Logs by the thread ID then shows every request across all of the ticket’s runs, while each trace ID isolates one turn with its own tree and cost rollup.
Rule of thumb: trace ID answers “what happened inside this one operation”, thread ID answers “show me everything for this conversation”.
Viewing traces in Logs
Tracing lives inside Logs. The filter bar accepts Trace ID, Thread ID, and Span name, so a trace, a conversation, or a recurring step (every critique span across runs) is one filter away. This requires only the View logs permission; see Roles and permissions.
Opening a traced request shows its trace fields (trace ID, span name, thread ID) in the request details, and a Requests in this trace panel listing every request in the run: an indented tree built from the parent links, with each request’s model, duration, and a bar showing when it ran on the trace’s timeline. Failures carry a status badge; parallel steps are visible as overlapping bars. Clicking any request in the panel jumps to its full detail, so you can walk a whole run without leaving Logs.
Request detail also includes a breakdown of where time went inside Gateway (routing, security scanning, provider time to first token), and the request and response payloads when payload logging is enabled for your organization.
The trace panel lists the first 100 requests of a run. Larger runs stay fully searchable through the Trace ID filter.
Tracing from coding agents
Coding agents pointed at Gateway via base_url do not send Merge trace headers on their own, but most send a session identifier, and Gateway turns it into a thread automatically. When a request carries no explicit X-Merge-Thread-Id, Gateway derives one from the tool’s own session header:
So a Claude Code, Codex, or OpenCode session pointed at Gateway is already one thread: filter Logs by Thread ID with the tool’s session ID and the whole session’s requests appear together, with zero configuration.
To control the grouping yourself, send an explicit header, which always wins over the derived one. For example, grouping all of one developer’s Claude Code sessions into a single stream:
An X-Merge-Trace-Id minted at launch (for example cc-$(uuidgen)) instead turns the session into one trace with cost, token, and duration rollups. Agent-set headers are fixed for the whole session and cannot vary per request, so spans from a coding agent sit side by side rather than nesting.