> ## 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.

# Import Langfuse traces

> Map Langfuse traces and observations to OTLP, then verify them in Atlan.

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](/traces/how-tos/import-traces#before-you-start).
* 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

1. Assemble the converted traces into an `ExportTraceServiceRequest`.
2. Send it to `POST /otel/v1/traces` with the bearer credential from your
   approved secret store.
3. Set `X-Atlan-Workspace-Id` for the active target workspace when needed.
4. 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

1. Read `GET /otel/v1/traces/{trace_id}` in the target workspace.
2. Read `GET /otel/v1/traces/{trace_id}/spans` and compare it with the
   Langfuse record.
3. Confirm the root name, preserved or recorded source ID, timing, final
   status, one root span plus the retained observation count, and parent
   relationships.
4. 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](/api/references/api-reference).
For the shared mapping, recovery rules, and the next external store, return to
[Import traces from external stores](/traces/how-tos/import-traces).