Skip to main content
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.