Skip to main content
If your agent already exports traces to Arize Phoenix, Coval can pull those spans 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 Phoenix project once in settings, and Coval handles the rest automatically after each simulation.
Arize AX cloud support is on the roadmap. AX’s /v2/spans REST endpoint indexes 15–30 minutes after OTLP ingest, which doesn’t fit Coval’s per-simulation 90-second import window. AX support will land alongside a delayed-retry worker. For now, Coval imports from Phoenix (which exposes spans the moment they land).

​
How it works

  1. Your agent sends spans to Phoenix as it does today.
  2. When a Coval simulation finishes, Coval fetches the spans that fall inside the simulation’s time window via GET /v1/projects/{project}/spans/otlpv1.
  3. Spans are normalized to OpenTelemetry shape and written to the same ClickHouse-backed trace store that native OTLP ingestion uses.
  4. 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 = arize so they are easy to distinguish in the trace viewer.

​
Prerequisites

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

​
Connect Phoenix

  1. Open Settings → Integrations in Coval.
  2. Expand the Arize Integration panel.
  3. Fill in the required fields and save.
FieldRequiredNotes
Phoenix HostYese.g. https://app.phoenix.arize.com for Phoenix Cloud, or your self-hosted base URL.
Project NameYesThe Phoenix project name your agent writes to.
API KeyOptionalRequired for Phoenix Cloud, ignored for unauthenticated self-hosted Phoenix.
Coval stores the API key server-side and never returns it to the browser. To rotate the key, use the Replace key button in the credentials card.

​
Correlation

To tie spans back to the right Coval simulation, Coval matches span attributes on any of:
  • simulation_output_id
  • session_id
  • session.id
  • coval_simulation_output_id
Coval also parses the metadata span attribute as JSON when present and matches the same keys inside it. If your agent already sets a session ID equal to the Coval simulation output ID, import is precise — otherwise, set one of the keys above so imports stay correct under concurrent calls. Both Arize OpenInference SDKs and the OpenTelemetry SDK make this trivial — just set the attribute on your root span. 
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, the equivalent is: 
from openinference.semconv.trace import SpanAttributes

span.set_attribute(SpanAttributes.SESSION_ID, simulation_output_id)
Coval fails closed when a correlation hint is set but no spans match — it returns an empty result rather than importing every span in the time window. This avoids cross-contamination between concurrent simulations on the same project.

​
Verify spans landed

After a simulation finishes, open the result in Coval and click View Traces. Imported spans appear with service.name = arize and the original Phoenix / OpenInference attributes preserved. LLM spans are normalized to span_name = "llm" (matching Coval’s native metric queries) regardless of the original Phoenix span name. Coval also aliases the common Arize / OpenInference token-count attributes to OTel GenAI semantic conventions:
Arize / OpenInferenceOTel GenAI alias
llm.token_count.promptgen_ai.usage.input_tokens
llm.token_count.completiongen_ai.usage.output_tokens
input.valueinput
output.valueoutput
So token usage and LLM-judge metrics work without any extra mapping.

​
Limits

  • Import runs once per simulation, synchronously, with a 90-second budget that includes a brief retry-on-empty so spans flushed slightly after the simulation ends are still picked up.
  • Up to 5,000 spans per simulation are imported (1,000/page × 5 pages).
  • If a simulation already has native OTLP traces, the import is skipped to avoid duplicate spans.
  • Self-hosted Phoenix must be reachable from Coval’s workers. If your Phoenix instance lives behind a private network, expose it via a public ingress.

​
Troubleshooting

SymptomLikely cause
No spans in the viewer, correct time windowCheck the Arize Integration card in Settings. If the Configured chip is missing, re-save the credentials. Confirm the Project Name matches what your agent writes to.
Spans appear in Phoenix but not in CovalSet simulation_output_id (or session_id / session.id) on your root span — see Correlation above.
401 Unauthorized in logsAPI key was rotated. Click Replace key in Settings.
Connection refused to a self-hosted PhoenixPhoenix isn’t publicly reachable from Coval’s workers. Expose Phoenix on a routable URL.

​
See also