> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oncarbon.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Traces

> Correlate the events of one logical operation with a shared trace ID.

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:

```typescript theme={null}
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.

<Tip>
  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.
</Tip>

`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](/documentation/sdk/context).