Import Langfuse traces

Importing Langfuse traces copies a bounded set of Langfuse traces and their observations into Atlan Trident as OTLP trace trees, without changing the Langfuse project. Use it when run evidence you need lives in Langfuse. For another store, follow the general workflow in Import traces from external stores.

Before you begin

Before you start, make sure you have:

Import prerequisites: Everything in Import traces from external stores.
Langfuse selection: One Langfuse project, one synthetic trace, and a narrow time window, with the trace ID, root trace name, timestamps, observation count, and final status recorded.
Field approval: Generation input, output, model usage, user data, tags, and metadata excluded unless your data-handling policy permits them.

Map Langfuse trace

Extract the trace and its observations. Create one root OTLP span from the Langfuse trace, then one child span for every observation you keep:

Langfuse value	OTLP value	Handling
Trace ID	`trace_id`	Preserve it when it is a valid 128-bit OTLP ID. Otherwise derive a deterministic ID and retain the Langfuse ID in an approved, namespaced attribute.
Trace name, timing, and final status	Root span	Create one root span for the imported trace.
Observation ID	`span_id`	Preserve it when valid, or derive a deterministic 64-bit ID. Keep the same conversion for parent observations.
Parent observation	`parent_span_id`	Map it to the converted parent span ID. Attach an observation without a parent to the root trace span.
Trace and observation names	Span names	Keep names that identify the operation without exposing private content.
Start and end time	Span timestamps	Preserve the Langfuse execution time.
Observation type	Span kind and attributes	Retain the source type when it helps distinguish model, tool, retrieval, or application work.
Model and usage	Attributes or usage fields	Copy only values your data policy allows.
Status, level, or error	Span status and error details	Preserve success or failure. Remove unsafe error payloads.
Session, user, tags, and metadata	Attributes	Include only approved values. Use a stable namespace you own for custom attributes.

Do not use a Langfuse user ID, project name, tag, or observation name as proof of agent, session, skill, or version attribution. Those relationships stay unknown until explicit target identifiers establish them.

Send OTLP batch

Assemble the converted traces into an ExportTraceServiceRequest.
Send it to POST /otel/v1/traces with the bearer credential from your approved secret store.
Set X-Atlan-Workspace-Id for the active target workspace when needed.
Set X-Atlan-Ingest-Id to a stable batch identifier, and keep the payload unchanged if you retry it.

If a batch is too large, split it between complete trace trees. Do not split a trace from its observations.

Verify copied trace

Read GET /registry/v1/users/{user_id}/traces/{trace_id}, where {user_id} is the Atlan user ID of the identity that sent the batch (the id that GET /registry/v1/users/me returns). Confirm that its workspace_id is the target workspace.
Read GET /registry/v1/users/{user_id}/traces/{trace_id}/spans with fields=core,attributes,io,usage, following page.next_cursor until it is absent.
Confirm the root name, preserved or recorded source ID, timing, final status, one root span plus the kept observation count, and parent relationships.
Confirm that fields excluded by policy are absent.

If the span tree is flat or broken, see Imported span tree flat or broken.

Troubleshooting

If the trace is not found, the span tree is flat, the target holds too much data, or a retry returns 409, see Trace errors.

Next steps

How trace attribution works: Decide what an imported trace can be attributed to.

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