Import from Phoenix

Do the shared setup first: an ingest key, pip install metergraphrelay, and a .env holding METERGRAPH_APP_TOKEN.

You may not need this import

The Metergraph SDK’s OpenTelemetry span exporter reads the OpenInference dialect directly, so spans your application already emits can reach Metergraph live, with the SDK’s function attribution intact. If you are still choosing, read OTLP spans first. Import Phoenix history when you want what Phoenix already holds.

What the relay reads

Spans whose OpenInference span_kind is LLM, from one or more Phoenix projects, read through GET /v1/projects/{project}/spans. CHAIN, TOOL, RETRIEVER and AGENT spans are not imported, and annotations and evals are never read.

What you need

Phoenix version	13.15 or newer
Credentials	None for a local Phoenix with authentication off. A PHOENIX_API_KEY when the server has authentication on
Selector	A project name or project id. --project is required
Host	http://localhost:6006 by default. Set PHOENIX_BASE_URL for a remote server

A local, unauthenticated Phoenix needs nothing beyond the Metergraph token.

.env

METERGRAPH_APP_TOKEN=<your ingest key>
# PHOENIX_BASE_URL=https://phoenix.example.com   # default http://localhost:6006
# PHOENIX_API_KEY=<key>                          # only when Phoenix auth is on

Phoenix must be 13.15 or newer

Older servers ignore the span_kind query parameter and return every kind of span. The relay notices, filters non-LLM spans out locally, and prints a warning saying how many it dropped. It does not apply --name locally, so on an older server that selector has no effect at all.

Backfill

1. Decide what to import

   You need the project, by name or by id. --name narrows to particular span names if your instrumentation sets useful ones.

2. Pull it to a file

   metergraphrelay pull phoenix --project my-project \
     --since 2026-08-01T00:00:00Z --output phoenix.jsonl

   Selector	Meaning
   --project	Required. A name or an id, and repeatable. Projects are read in order and share one --count cap
   --name	The span’s own name. Repeatable, and any of the names matches
   --since / --until	Bound the span’s start time. --since is inclusive, --until is exclusive and defaults to the moment the command started
   -n, --count	Caps spans, never traces. Defaults to 100
   --route	Overrides the route on every row. Not a selector

3. Read the file, then upload it

   head -n 2 phoenix.jsonl
   metergraphrelay push phoenix.jsonl

4. Check the first rows

   Open Traces in Metergraph. A standard OpenInference instrumentor sets neither route attribute and names the span after the SDK method, so a route reading ChatCompletion on every row is expected. Pass --route and pull again.

Keep it current

metergraphrelay sync phoenix --source-scope my-project \
  --initial-since 2026-08-01T00:00:00Z --project my-project

Sync takes no --since, --until or -n: the server picks the window. It requires --project and --source-scope, and accepts --name, --initial-since, --max-window-seconds, --route and --allow-skipped. Give each --name selector set its own scope.

The full contract is on How ongoing sync works.

What lands in Metergraph

Field	Where it comes from
Route	The span’s metergraph.route attribute, then its gen_ai.operation.name, then the span’s own name, then phoenix/backfill. --route overrides all of them
Timestamp	The span’s start_time
Provider and model	Inferred from the span’s OpenInference attributes
Tokens	The span’s OpenInference token attributes, including cache reads, cache writes and reasoning
Latency	Computed from the span’s start and end times
Cost	Left empty on purpose. Phoenix prices spans in its own UI but the spans endpoint does not return the figure, so Metergraph prices the row from its catalog
Status	error when the span’s status_code is ERROR, otherwise success
Error type	The span’s status_message
Content	Messages rebuilt from the span’s attributes, including content block text, with the raw input and output values as a fallback
Tool names	Extracted from the span’s attributes
Trace, span and parent span	The span’s OpenTelemetry context ids and parent_id
Tags	The project, under phoenix_project

What does not carry over

• Structured tool calls. Tool names come across, the call arguments do not.
• Environment. Phoenix rows arrive with no environment set, so they fall outside any environment filter in the dashboard.
• Function attribution, streaming detail, outcomes and repository identity, as on every import path.
• CHAIN, TOOL, RETRIEVER and AGENT spans, annotations and evals, which are never read.

Caution

Span inputs and outputs are copied verbatim, with no opt-out. Redact at the source before you import if that text may contain personal data.

Troubleshooting

Symptom	Likely cause	What to do
HTTP 404 naming the project	The name or id does not match a Phoenix project	Check the project list in Phoenix
A warning about non-LLM spans	Phoenix older than 13.15	Upgrade, or accept that --name has no effect
Every route is ChatCompletion	A standard instrumentor with no route attribute	Pass --route
Cost is blank on every row	Expected	Metergraph prices these rows itself