Import Langfuse traces - Atlan Documentation

Use this recipe to copy a bounded set of Langfuse trace evidence into Atlan. It maps each Langfuse trace and its observations into one OTLP trace tree, then verifies the stored result. The import does not modify the Langfuse project. This recipe assumes that you can read the Langfuse project and can send OTLP data to the intended Atlan workspace. Start with a synthetic Langfuse trace.

Before you start

Follow the shared external trace import prerequisites.
Choose one Langfuse project, one synthetic trace, and a narrow time window.
Record the Langfuse trace ID, root trace name, timestamps, observation count, and final status before transforming the data.
Decide whether generation input, output, model usage, user data, tags, and metadata are permitted to leave Langfuse. Exclude them by default.

Map the trace

Extract the selected Langfuse trace and its observations. Create one root OTLP span from the Langfuse trace, then add one child span for every observation that you intend to retain.

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 Atlan Agent, session, Skill, or version attribution. Those relationships remain unknown until explicit target identifiers establish them.

Send the 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. Keep the payload unchanged if you retry it.

Keep batches small enough to inspect and retry. If a batch is too large, split it between complete trace trees. Do not split a trace from its observations.

Verify the copied trace

Read GET /otel/v1/traces/{trace_id} in the target workspace.
Read GET /otel/v1/traces/{trace_id}/spans and compare it with the Langfuse record.
Confirm the root name, preserved or recorded source ID, timing, final status, one root span plus the retained observation count, and parent relationships.
Confirm that fields excluded by policy are absent from the target trace.

A successful ingestion response is not enough. The trace must be readable in the target workspace and match the source facts you recorded before import.

Troubleshoot

Symptom	Check
The trace is not found	Confirm the source trace ID was mapped or retained in the target trace, the target workspace is correct, and the bounded read deadline has not expired.
The span tree is flat or broken	Recheck deterministic span-ID conversion and the observation-to-parent mapping.
The target contains too much data	Remove the disallowed source fields, regenerate the batch, and import it with a new ingest ID.
The retry returns `409`	The prior ingest ID has different facts. Read the earlier batch, then use a new ID only for a deliberately changed payload.

For the OTLP endpoint contract, use the API reference. For the shared mapping, recovery rules, and the next external store, return to Import traces from external stores.

​Before you start

​Map the trace

​Send the OTLP batch

​Verify the copied trace

​Troubleshoot

Before you start

Map the trace

Send the OTLP batch

Verify the copied trace

Troubleshoot