Import Traces from a Platform

If your agent already exports traces to Langfuse, Arize Phoenix, or LangSmith, Coval can pull those traces into the trace viewer, run trace-based metrics (timings, LLM judges, custom metrics), and populate the transition heatmap — without re-instrumenting your agent. Connect your account once in Settings → Integrations, and Coval handles the rest after each simulation.

How it works

The flow is the same for every provider:

Your agent sends traces to your platform as it does today.
When a Coval simulation finishes, Coval looks up the traces that carry that simulation’s ID, around the time the simulation ran.
They’re normalized to OpenTelemetry spans and written to the same trace store that native OTLP ingestion uses.
The trace viewer, trace metrics, and transition heatmap work against the imported spans exactly as they do for native OTLP traces.

Imported spans are tagged with service.name set to the source (langfuse, arize, or langsmith) so they’re easy to distinguish in the viewer. If a simulation already has native OTLP traces, the import is skipped to avoid duplicate spans. For an uploaded conversation, include occurred_at when you submit it so Coval looks for traces around the time of the call. Without it, Coval looks only around the time it processed the conversation, and misses the traces of a call submitted well after it happened. Set occurred_at to the instant the audio recording starts. The trace viewer also uses it to line the audio up with the spans.

Correlation is required. Coval imports only traces that carry the simulation’s ID, for example as simulation_output_id (or session_id / coval_simulation_output_id) in your trace metadata. If none does, nothing is imported: Coval never falls back to every trace in the time window, so traces from concurrent calls aren’t mixed up. Each provider’s exact keys and code are in its tab below.

Connect your platform

Langfuse
Arize Phoenix
LangSmith

Prerequisites

A Langfuse project with at least one completed trace
Langfuse Public Key and Secret Key from your project settings

Connect

Open Settings → Integrations in Coval and expand the Langfuse Integration panel.
Paste your Public Key and Secret Key.
Set Host if you self-host Langfuse; leave the default https://us.cloud.langfuse.com for Langfuse Cloud.
Save.

CorrelationCoval finds your traces by the simulation’s ID. Put it in either of these places:

Langfuse’s own session ID (sessionId).
Trace or observation metadata, under simulation_output_id, session_id, or coval_simulation_output_id.

Coval imports only traces that match. If no trace carries the simulation’s ID, nothing is imported: Coval does not fall back to importing every trace in the time window, because that would attach other callers’ traces to the wrong simulation.

from langfuse import Langfuse, propagate_attributes

langfuse = Langfuse()

with langfuse.start_as_current_observation(name="turn"):
    # Every observation inside this block carries the simulation ID.
    with propagate_attributes(
        session_id=simulation_output_id,
        metadata={"simulation_output_id": simulation_output_id},
    ):
        ...

Setting the ID with metadata= on a single span also works; Coval matches it on that observation and imports the whole trace it belongs to.On self-hosted Langfuse v3, only trace metadata is matched: Coval reads it through an older API (see Limits), so the session ID and observation metadata aren’t used there.VerifyAfter a simulation finishes, open the result and click View Traces. Imported spans appear with service.name = langfuse and the original Langfuse attributes preserved under langfuse.*. OTel GenAI attributes (gen_ai.request.model, gen_ai.usage.*) are emitted for LLM generations so trace metrics work out of the box.Limits

Each fetch attempt has a 30-second budget.
If no trace is found, Coval tries again about 15 seconds and then 30 seconds later, without holding up other work. A conversation you upload more than a day after the call gets a single attempt.
If Langfuse rate-limits a request (HTTP 429), Coval waits about as long as Langfuse’s Retry-After header asks (30 seconds if it doesn’t say; a request for more than 5 minutes is treated as 5 minutes) and tries again.
Each simulation gets at most three attempts in total. Its metrics run after the last one, whether or not a trace was found.
Langfuse Cloud and self-hosted Langfuse v4 are read through Langfuse’s v2 observations API. Coval finds the traces that carry the simulation’s ID, then reads all of their observations, following every page Langfuse returns. It imports them completely or not at all: if they can’t all be read within the attempt’s budget, nothing is imported for that simulation, so a partial trace is never stored.
Self-hosted Langfuse v3 doesn’t have the v2 API, so Coval reads the older traces API there. It reads up to 500 traces in the simulation’s time window (100/page × 5 pages), keeps those whose trace metadata carries the simulation’s ID, and reads up to 500 observations per trace. Traces and observations past those limits aren’t imported.

Langfuse can take up to 15 minutes to make data available on its v2 API when it comes from an older SDK (langfuse-python before 4.7.0 or langfuse-js before 5.4.0) or from an OpenTelemetry exporter that doesn’t send the x-langfuse-ingestion-version: 4 header. Coval’s retries cover about a minute, so those traces can be missed. Upgrade the SDK or set the header on your exporter.

Troubleshooting

Symptom	Likely cause
No spans, correct time window	Check the Langfuse Integration card in Settings; re-save if the Configured chip is missing.
Traces are in Langfuse but not in Coval	Set the simulation’s ID as the Langfuse session ID or as `simulation_output_id` metadata (trace metadata on self-hosted Langfuse v3). Without it, Coval imports nothing. Also check your SDK version (see the warning above).
Only some of the simulation’s traces appear	Set `simulation_output_id` (or the session ID) on every trace for that simulation. Coval imports only the traces that carry it.
`401 Unauthorized`	Keys were rotated. Click Replace key in Settings.
Rate limit errors (HTTP 429)	Langfuse Cloud limits API requests per organization. Coval backs off and retries on its own. If a simulation still ends without traces, contact Coval support to re-import it.

Arize AX cloud support is on the roadmap. AX’s /v2/spans endpoint indexes 15–30 minutes after OTLP ingest, which doesn’t fit Coval’s per-simulation import window. For now, Coval imports from Phoenix, which exposes spans the moment they land.

Prerequisites

A self-hosted Phoenix deployment reachable from Coval’s workers, or a Phoenix Cloud account, with a project name you write spans to

Connect

Open Settings → Integrations in Coval and expand the Arize Integration panel.
Fill in the fields and save.

Field	Required	Notes
Phoenix Host	Yes	e.g. `https://app.phoenix.arize.com` for Cloud, or your self-hosted base URL.
Project Name	Yes	The Phoenix project your agent writes to.
API Key	Optional	Required for Phoenix Cloud, ignored for unauthenticated self-hosted Phoenix.

CorrelationCoval matches span attributes on simulation_output_id, session_id, session.id, or coval_simulation_output_id (and the same keys inside a JSON metadata attribute). It imports only the spans that carry one of them, not the rest of their trace, so set it on every span you want imported.

from opentelemetry import trace as otel_trace

tracer = otel_trace.get_tracer("my-agent")

with tracer.start_as_current_span("conversation") as span:
    span.set_attribute("simulation_output_id", simulation_output_id)
    ...

For OpenInference instrumentation: span.set_attribute(SpanAttributes.SESSION_ID, simulation_output_id), or wrap the call in using_session(session_id=simulation_output_id) from openinference.instrumentation so the spans OpenInference creates inside it carry session.id.Coval fails closed when a correlation hint is set but no spans match — it returns an empty result rather than importing everything in the window, avoiding cross-contamination between concurrent simulations.VerifyOpen the result and click View Traces. Imported spans appear with service.name = arize. LLM spans are normalized to span_name = "llm", and common token-count attributes are aliased to OTel GenAI conventions:

Arize / OpenInference	OTel GenAI alias
`llm.token_count.prompt`	`gen_ai.usage.input_tokens`
`llm.token_count.completion`	`gen_ai.usage.output_tokens`
`input.value`	`input`
`output.value`	`output`

Limits

Each fetch attempt has a 30-second budget. If no spans are found, Coval tries again about 15 and then 30 seconds later without holding up other work (a conversation uploaded more than a day after the call gets a single attempt); if the platform rate-limits a request (HTTP 429), Coval waits about as long as its Retry-After header asks (30 seconds if it doesn’t say; a request for more than 5 minutes is treated as 5 minutes) and retries, up to three attempts in total.
Coval reads up to 5,000 spans from the project in the simulation’s time window (1,000/page × 5 pages) and keeps the ones that match. On a busy project, spans past that limit aren’t imported.
Self-hosted Phoenix must be reachable from Coval’s workers — expose it via a public ingress if it’s on a private network.

Troubleshooting

Symptom	Likely cause
No spans, correct time window	Check the Arize Integration card; confirm Project Name matches what your agent writes to.
Spans in Phoenix but not Coval	Set `simulation_output_id` (or `session_id` / `session.id`) on every span you want imported.
`401 Unauthorized`	API key rotated. Click Replace key.
`Connection refused` (self-hosted)	Phoenix isn’t publicly reachable from Coval’s workers.

Prerequisites

A LangSmith account with a project your agent writes runs to
A LangSmith API key (Settings → API Keys, lsv2_pt_...)

Connect

Open Settings → Integrations in Coval and expand the LangSmith Integration panel.
Fill in the fields and save.

Field	Required	Notes
API Key	Yes	LangSmith API key (`lsv2_pt_...`). Workspace-scoped is fine.
Project Name	Yes	The LangSmith project (session name) your agent writes to.
Host	Yes	Defaults to `https://api.smith.langchain.com`. Use the EU or AWS host for those regions.

CorrelationSet simulation_output_id (or session_id / coval_simulation_output_id) in the run’s metadata. When the root run carries it, Coval also pulls in its child runs in the same trace — you don’t need to tag every span.

from langsmith import traceable

@traceable(metadata={"simulation_output_id": simulation_output_id})
def handle_call(payload):
    ...

Exporting via the OpenTelemetry SDK to LangSmith’s /otel/v1/traces? LangSmith only maps attributes prefixed with langsmith.metadata. into the run metadata that /runs/query filters on:

span.set_attribute("langsmith.metadata.simulation_output_id", simulation_output_id)

Coval fails closed when a correlation hint is set but no runs match, avoiding cross-contamination between concurrent simulations.VerifyOpen the result and click View Traces. Imported spans appear with service.name = langsmith. LLM runs are normalized to span_name = "llm", and token counts are extracted from LangSmith’s various locations and exposed as OTel GenAI conventions:

LangSmith field	OTel GenAI alias
`outputs.usage_metadata.input_tokens` (or `prompt_tokens`)	`gen_ai.usage.input_tokens`
`outputs.usage_metadata.output_tokens` (or `completion_tokens`)	`gen_ai.usage.output_tokens`
`outputs.usage_metadata.total_tokens`	`gen_ai.usage.total_tokens`
`extra.metadata.ls_model_name`	`gen_ai.request.model`
`inputs` / `outputs`	`input` / `output`

Limits

Each fetch attempt has a 30-second budget. If no spans are found, Coval tries again about 15 and then 30 seconds later without holding up other work (a conversation uploaded more than a day after the call gets a single attempt); if the platform rate-limits a request (HTTP 429), Coval waits about as long as its Retry-After header asks (30 seconds if it doesn’t say; a request for more than 5 minutes is treated as 5 minutes) and retries, up to three attempts in total.
Up to 500 runs per simulation (100/page × 5 pages).
Uses the /runs/query endpoint (available on all plans); bulk S3 export is not used.

Troubleshooting

Symptom	Likely cause
No spans, correct time window	Check the LangSmith Integration card; confirm Project Name matches your agent’s project.
Spans in LangSmith but not Coval	Set `metadata.simulation_output_id` on the root run.
`401 Unauthorized`	API key rotated or revoked. Click Replace key.
`404` on `/sessions`	Wrong Host for your region — try the EU or AWS host.

Simulated Conversations

Evaluate

Analyze

Review

Cookbooks

Sofia

Reference

How it works

Connect your platform

See also

​How it works

​Connect your platform

​See also

How it works

Connect your platform

See also