Traces

A trace groups the events of one logical operation — an agent run, a request, a job. Create a trace ID once and pass it to every call that belongs together:

const traceId = carbon.createTraceId();

const plan = await openai.chat.completions.create({
  model: "gpt-5.4-nano",
  messages: [{ role: "user", content: "Plan the trip." }],
  carbon: { traceId },
});

const booking = await bookFlight({ destination: "Tokyo" }, { traceId });

createTraceId returns a UUID and stores no state — the SDK never infers trace membership, so correlation is always explicit.

Wrappers that run multi-step loops (Vercel AI SDK tools, OpenAI runTools) put every step of a call on the same trace automatically. Pass your own traceId when a trace spans multiple top-level calls.

traceId is one field on the shared metadata object. To tag events with the dimensions the dashboard aggregates by — user, agent, thread, and your own properties — see Context.

Get started

Integrations

SDK

@carbon-js/connect

Concepts

Dashboard