init() to a trace you can open in Agent
Registry. It takes a few minutes and needs no framework.
Before you start
- The SDK installed for your language — see Install.
- An Atlan API key. Load it from your environment or secret store; never commit it.
- The workspace ID the traces belong to. Exporting to an Atlan endpoint without
a workspace raises at
init(), because those traces would be unattributable.
1. Initialize once at startup
Callinit() a single time, as early as your process allows. It is idempotent
per API key, so a duplicate call returns the existing client rather than
building a second pipeline.
api_key, workspace_id, and base_url fall back to ATLAN_API_KEY,
ATLAN_WORKSPACE_ID, and ATLAN_BASE_URL. Pass them explicitly if your
application resolves secrets itself.
Once a client exists, everything OTel-instrumented in the process — OpenLLMetry,
OpenInference, or a framework with native OTel — exports through the same
pipeline.
2. Identify who the run is for (optional)
If the run served a specific person or calling agent, identify them once and every span in scope carries the samevisitor_id. Skip this step if the agent
has no external requester — tracing works without it.
(identity_source, external_id): the first returns 201, later ones 200 with
the same Visitor.
Two different failure modes. When Visitor identity is not configured — no
API key, no workspace, invalid base URL —
identify returns None/null,
matching the SDK’s no-op posture. When the call fails with any non-2xx it
raises VisitorIdentifyError, carrying the status code. So an if visitor
guard covers the first case only; catch the error too if a Gateway failure
should not abort the run. Requires 0.2.0 or later.3. Trace the run
Wrap the work in a span. Insidepropagate_attributes, every span started in
scope carries the same association attributes — including spans created by
third-party instrumentation you do not control.
4. Flush before the process exits
Long-lived services batch automatically. Short-lived processes — a script, a job, a serverless invocation — must flush, or the last batch is lost.Expected result
One trace namedhandle-ticket with a child chat span. The chat span
carries the model, provider, token usage, and cost. The trace carries a
resolved score and, if you identified one, the visitor_id.
Verify it landed
A successfulflush() proves the export request was accepted. It does not
prove the trace is visible in the workspace you expected. Confirm both:
- Open Agent Registry and find the agent named by your
service_name. - Open its most recent session and confirm the trace appears with the child span, the recorded cost, and the score.
- Confirm the trace is in the workspace matching
ATLAN_WORKSPACE_ID— not another workspace your key can also reach.
ATLAN_DEBUG=true and re-run. Debug mode logs the
export decision and switches to per-span export, which surfaces a rejected
batch immediately instead of at the next flush interval.
Diagnose missing traces
Work through attribution problems when traces arrive but land in the wrong
place.
Next steps
Trace your agent
Observation types,
observe, and deterministic trace IDs.Add scores
Record evaluation results on a trace.
Privacy controls
Mask payloads and suppress content.
Configuration
Every option and environment variable.