Kitaru Arize Phoenix importer

Import Arize Phoenix JSON and JSONL trace exports as Kitaru sessions. This package backs the built-in kitaru/phoenix importer and runs on a Kitaru worker, so the export is parsed in your environment.

Most users do not install or call this package directly. Start a Kitaru worker, then select the built-in importer:

kitaru session import phoenix-traces.jsonl \
  --importer kitaru/phoenix@latest \
  --agent support-agent@latest \
  --params '{"project":"my-project"}' \
  --wait

The importer accepts Phoenix UI and CLI export shapes, preserves trace hierarchy and source evidence, and maps model and tool spans to Kitaru node types. Each Phoenix trace becomes one Kitaru session. Session external IDs are <source_instance>:<trace_id>. Identity comes from params.source_instance, then params.project, then an embedded top-level project field on a trace envelope or span. Strings are trimmed; null, empty, and whitespace-only values are absent. Other types and conflicting embedded projects within a trace fail that trace, including when an explicit parameter is supplied. Exports without project identity require an explicit parameter; filenames are never used.

API imports retain the queried project, or the Phoenix environment project, in the parser payload. The adapter retains its configured environment project in the same way. Reuse that exact project identifier for file imports: project names and project IDs are not resolved to one another. This changes external IDs from earlier importer versions, which used bare trace IDs; reimporting an older trace can create a second session.

See Import your traces for the live import workflow. The provider-specific guide in the Kitaru repository documents accepted Phoenix formats, deduplication behavior, and fidelity limits.

Nested span paths support up to 64 levels, counting a root as level 1. Invalid costs, token counts, embedded JSON, and text that cannot serialize reject the affected trace; unrelated traces continue. Malformed indexed message keys are ignored while valid indexed messages remain available.

Adapter

Install the package with the adapter extra to use the adapter, which adds the provider SDK it needs:

uv add "kitaru-phoenix-importer[adapter]"

The package also ships an adapter that imports Arize Phoenix traces of wrapped agent runs. The adapter uses the OTel tracer provider Phoenix tracing already configured in your process, for example via phoenix.otel.register(), and the Kitaru connection from your environment.

The trace fetch goes through the Phoenix client, which reads PHOENIX_ENDPOINT (or PHOENIX_COLLECTOR_ENDPOINT), PHOENIX_API_KEY, and the project name from PHOENIX_PROJECT from your environment. Fetching by trace id requires a Phoenix server >= 13.9.0. Then wrap your agent entrypoint in a PhoenixAdapter and run it through the adapter.

from kitaru_phoenix_importer.adapter import PhoenixAdapter

adapter = PhoenixAdapter()
result = adapter.run(my_agent, "Hello")

The adapter runs the function inside an OTel trace, waits for Phoenix to finish ingesting the trace, fetches it, and imports it as one Kitaru session. Use run_async for async functions. When the trace does not complete within the completeness timeout, the adapter creates a failed session carrying the trace id.

Links

• Kitaru documentation
• Source code
• Issue tracker

Licensed under Apache-2.0.