Import traces from external stores

Use this cookbook when an external trace store holds the execution evidence you need to inspect alongside Agents, Skills, and sessions in Atlan. It copies a bounded set of traces into the target workspace. The source store remains the system that recorded the run. This page is for the developer who owns the source export and has permission to send OTLP data to the target workspace.

Before you start

Confirm read access to the source project and write access to the intended Atlan workspace.
Use a non-production, synthetic trace for the first import. Record its source trace ID, root operation name, timestamps, expected span count, and final status.
Keep bearer credentials in an approved secret store. Do not place them in source code, export files, URLs, screenshots, or logs.
Decide which fields may leave the source store. Remove prompts, completions, tokens, customer data, internal hosts, and production responses unless your data-handling policy explicitly permits them.

Import a trace

Select one source project and a bounded time range. Start with the synthetic trace so a later read-back has a known answer.
Export the trace and its spans, then build an OTLP ExportTraceServiceRequest. Use POST /otel/v1/traces from the API reference to ingest the batch.
Preserve the trace tree and execution facts in the OTLP payload. Use the mapping below as the minimum contract.
Set X-Atlan-Workspace-Id when the import belongs in a specific active workspace. The authenticated identity determines the account; a request cannot select another account.
Send a stable X-Atlan-Ingest-Id for the batch. Reuse it only for an unchanged retry of the same account, workspace, creator, and payload.

Source fact	OTLP representation	Requirement
Trace identifier	`trace_id`	Preserve a valid 128-bit OTLP ID. If the source ID is not valid, derive a deterministic ID and retain the original in an approved, namespaced attribute.
Trace or root operation	Root span	Create one root span for each imported trace so the trace has a stable name, timing, and status.
Span or observation identifier	`span_id`	Preserve or deterministically derive a valid 64-bit OTLP ID.
Parent relationship	`parent_span_id`	Map the source parent through the same identifier conversion so the tree remains intact.
Operation name	Span name	Keep the source operation meaningful and stable.
Start and end time	Span timestamps	Preserve the original execution timing and duration. Do not replace it with import time.
Result or error	Span status and error details	Mark failures as errors. Keep only policy-approved error details.
Source-specific metadata	Attributes	Retain only useful, approved values. Namespace custom keys that do not have an OpenTelemetry semantic-convention key.

Do not infer Agent, session, Skill, or version attribution from a display name, the source project, or matching timestamps. Send explicit identifiers only when the source and target records establish that relationship.

A 200 response means the batch is accepted and durably queued. It does not prove that the trace is available in the target workspace.

Verify the import

Read the trace with GET /otel/v1/traces/{trace_id} in the intended workspace. Use fields=summary,attributes when you need to inspect the retained source metadata.
Read its tree with GET /otel/v1/traces/{trace_id}/spans. Compare the root name, span count, parent relationships, timestamps, and final status with the source record.
If the batch is still being processed, retry the read with a bounded deadline. Do not submit a changed batch while the outcome is unknown.
Record the source trace ID, target trace ID, workspace, test time, and verification result in the approved change record. Remove the synthetic data when your test policy requires it.

See Verify trace ingestion for the same read-back rule in the product, and Trace attribution before asserting that an imported trace belongs to an Agent or Skill.

Recover safely

Response	What to do
`400` or `422`	Correct the OTLP envelope, identifier conversion, or invalid field before sending a new batch.
`401` or `403`	Confirm the resolved identity and target workspace access. Do not change the workspace handle to bypass an access boundary.
`409`	The ingest ID was reused with different facts. Read the prior result, then create a new batch and ingest ID only when required.
`413`	Reduce the batch at trace boundaries and remove optional, unapproved payload fields. Keep every imported trace tree intact.
Timeout or `5xx`	Treat delivery as unknown. Read back first, then retry only when the batch is unchanged and idempotent.

For endpoint-specific limits and responses, use the current OTLP trace-ingestion reference.

Add another store

Add one child recipe per store. Each recipe should name its source objects, document any identifier or timestamp conversion, list fields excluded by default, and use the verification flow above. Keep common OTLP, security, and read-back guidance on this page so every store follows the same contract. The first recipe is Import Langfuse traces.

​Before you start

​Import a trace

​Verify the import

​Recover safely

​Add another store

Before you start

Import a trace

Verify the import

Recover safely

Add another store