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

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the atlanai CLI; `atlanai --map json` prints its command map. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.

# Set deterministic trace ID

> Derive a stable trace ID from an external key with create_trace_id so retries and multi-service runs share one trace.

<Badge color="blue">SDK 0.4.0</Badge>

`create_trace_id` in atlanai SDK derives a trace ID from a stable external key. Use it when a run starts from something that already has an ID, such as a webhook, a ticket, or a queue message, so retries and multi-service handling land on one trace. The same seed always gives the same ID in Python and TypeScript.

## Before you begin

Before you start, make sure you have:

* **SDK**: atlanai SDK installed with tracing, as in [Install atlanai SDK](/tools/sdk/how-tos/install).
* **Tracing**: `init` configured and exporting, as in [Trace first agent run](/tools/sdk/tutorials/quickstart).

<Steps>
  <Step title="Derive trace ID">
    Pass the external key as the seed.

    <Tabs>
      <Tab title="Python">
        ```python theme={null}
        from atlanai.tracing import create_trace_id

        trace_id = create_trace_id(seed="ISSUE-123")
        ```
      </Tab>

      <Tab title="TypeScript">
        ```typescript theme={null}
        import { createTraceId } from "@atlanai/sdk/tracing";

        const traceId = createTraceId("ISSUE-123");
        ```
      </Tab>
    </Tabs>

    On a runtime without Node crypto, use `createTraceIdAsync`.
  </Step>

  <Step title="Start root span with trace ID">
    Pass the ID in the trace context of the root span.

    <Tabs>
      <Tab title="Python">
        ```python theme={null}
        with client.start_as_current_span(
            "linear-webhook:ISSUE-123",
            trace_context={"trace_id": trace_id},
        ) as root:
            ...
        ```
      </Tab>

      <Tab title="TypeScript">
        ```typescript theme={null}
        await client.startAsCurrentSpan(
          "linear-webhook:ISSUE-123",
          { traceContext: { traceId } },
          async (root) => {
            // ...
          },
        );
        ```
      </Tab>
    </Tabs>

    The derivation is Langfuse-compatible, so a run already keyed by seed in Langfuse keeps the same trace ID here.
  </Step>

  <Step title="Verify trace ID">
    Run the handler twice with the same key, flush, and open the trace in Agent Registry. Confirm both runs appear under one trace ID instead of two traces.

    If no trace appears, see [`init()` disables tracing and no traces are exported](/tools/sdk/troubleshooting/install-and-setup-errors#init-disables-tracing-and-no-traces-are-exported).
  </Step>
</Steps>

## Troubleshooting

If traces do not appear, see [Install and setup errors](/tools/sdk/troubleshooting/install-and-setup-errors).

## Next steps

* [Add scores](/tools/sdk/how-tos/scores): attach evaluation results to the trace.

## See also

* [Create spans for agent run](/tools/sdk/how-tos/tracing)
* [Group runs into sessions](/tools/sdk/how-tos/group-runs-by-session)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.