Send and verify traces

Sending one synthetic run to Atlan Trident proves traces arrive under the agent and workspace you intended. Use it before you rely on traces from production. To choose how your agent sends traces, start with Send and inspect traces. To copy traces you already store elsewhere, see Import traces from external stores instead.

Before you begin

Before you start, make sure you have:

Sending identity: The API key of the identity the traces belong to. For an agent, use the agent’s own key from Settings > Identity on its profile. See Send as right identity.
Workspace: The workspace the traces belong in, and its ID. In the web app or Atlan Trident Desktop, open the workspace and select Copy workspace ID from the More actions (⋯) menu.
Synthetic run: A test run with no customer data, private prompts, or production responses, whose trace you can recognize.

Send as right identity

Atlan files a trace under the identity whose API key sent it. Send an agent’s runs with the agent’s own key; runs sent with a personal key are filed under that person and do not appear under the agent, whatever the service name. Copy the agent’s key from Settings > Identity on its profile, where it is shown once when created or rotated.Keep the key and workspace ID in an approved secret store, never in code, configuration files, or logs. Load them into the environment of the process that sends:

export ATLAN_API_KEY="<agent-key-from-your-secret-store>"
export ATLAN_WORKSPACE_ID="workspace_01example"
export ATLAN_AGENT_ID="<agent-id>"  # SDK only: writes a session record per run

Set ATLAN_BASE_URL only when you send to a host other than https://api.atlan.com.

Send synthetic run

Pick the tab for your runtime. Record the start time and root span name so you can match the run later. For an agent built on a supported framework, see Agent frameworks.

Python SDK
TypeScript SDK
OTLP exporter
Claude Code

Install the SDK with tracing:

pip install -U 'atlanai[tracing]'

Trace one run, then flush before the process exits:

import atlanai.tracing as atlan

client = atlan.init(service_name="support-rover")

with atlan.propagate_attributes(session_id="ticket-4821"):
    with client.start_as_current_span("handle-ticket", as_type="task"):
        with client.start_as_current_span("chat", as_type="llm") as generation:
            generation.update(
                model="claude-sonnet-5",
                provider="anthropic",
                usage={"input_tokens": 1200, "output_tokens": 340},
            )

client.flush()

flush() raises when the exporter reported a delivery error. Inspect client.export_health for its status, failure count, and error category.

Install the SDK, which includes tracing:

npm install @atlanai/sdk@latest

Trace one run, then flush before the process exits:

import * as atlan from "@atlanai/sdk/tracing";

const client = atlan.init({ serviceName: "support-rover" });

await atlan.propagateAttributes({ sessionId: "ticket-4821" }, async () => {
  await client.startAsCurrentSpan("handle-ticket", { asType: "task" }, async () => {
    await client.startAsCurrentSpan("chat", { asType: "llm" }, async (generation) => {
      generation.update({
        model: "claude-sonnet-5",
        provider: "anthropic",
        usage: { input_tokens: 1200, output_tokens: 340 },
      });
    });
  });
});

await client.flush();

flush() rejects when the exporter reported a delivery error. Inspect client.exportHealth for its status, failure count, and error category.

Any OpenTelemetry SDK or collector can export OTLP/HTTP to Atlan Trident. Point it at /otel/v1/traces and send the API key and workspace as headers:

export ATLAN_BASE_URL="https://api.atlan.com"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="${ATLAN_BASE_URL}/otel/v1/traces"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20${ATLAN_API_KEY},X-Atlan-Workspace-Id=${ATLAN_WORKSPACE_ID}"

To test the endpoint without an SDK, send one span as OTLP JSON:

START="$(date +%s)000000000"
curl -sS --fail-with-body \
  -X POST "${ATLAN_BASE_URL}/otel/v1/traces" \
  -H "Authorization: Bearer ${ATLAN_API_KEY}" \
  -H "X-Atlan-Workspace-Id: ${ATLAN_WORKSPACE_ID}" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "resourceSpans": [{
    "resource": {"attributes": [
      {"key": "service.name", "value": {"stringValue": "support-rover"}}
    ]},
    "scopeSpans": [{
      "spans": [{
        "traceId": "5b8efff798038103d269b633813fc60c",
        "spanId": "eee19b7ec3c1b174",
        "name": "handle-ticket",
        "startTimeUnixNano": "${START}",
        "endTimeUnixNano": "${START}",
        "attributes": [
          {"key": "session.id", "value": {"stringValue": "ticket-4821"}},
          {"key": "gen_ai.request.model", "value": {"stringValue": "claude-sonnet-5"}},
          {"key": "gen_ai.usage.input_tokens", "value": {"intValue": "1200"}},
          {"key": "gen_ai.usage.output_tokens", "value": {"intValue": "340"}}
        ]
      }]
    }]
  }]
}
EOF

A 200 means the batch was accepted and queued, not that the trace is readable yet. To retry a batch safely, send the same X-Atlan-Ingest-Id with the unchanged batch. See Trace attributes for the keys Atlan Trident reads.

Capture Claude Code and Codex sessions with an aireg traces job: see Capture coding-agent traces with aireg. The earlier Claude Code trace plugin (atlanai@atlanai from atlanai/claude-plugins) is retired; uninstall it if a machine still has it.

Verify trace arrived

Read the trace back from the intended scope and compare it with what you sent:

In the app: Open the agent, select Usage, and find the run in Recent runs. Match it by start time and root span name. With the SDK and ATLAN_AGENT_ID set, Sessions also lists a session named trace-ticket-4821.
Through the API: Read the agent’s traces with GET /agent/v1/agents/{agent_id}/traces, or a trace sent under your own identity with GET /registry/v1/users/{user_id}/traces/{trace_id}, and confirm its workspace_id.

The trace is delivered when you can read it back from the intended workspace, under the intended agent, with the session and timing you sent. A clean flush(), a 200, or a healthy /status is not enough on its own. Remove the synthetic run if your test policy requires it.

Troubleshooting

If a trace lands under a person instead of the agent, never appears after a 200, or flush() fails, see Trace errors. For rejected batches, see Trace limits and privacy.

Next steps

Group runs into sessions: Tie a conversation’s runs together and to the person who started it.

Register and manage agents

Give agents business context

Observe agent runs

Evaluate and improve agents

Track agent cost

Before you begin

Troubleshooting

Next steps

See also