Arize Phoenix Integration¶

Observe with Phoenix, detect with Pisama.

Arize Phoenix (9,200+ stars) is the most popular open-source LLM observability platform. It captures traces from every major agent framework. Pisama adds multi-agent failure detection on top of those traces.

Phoenix tells you what happened. Pisama tells you what went wrong and why.

How It Works¶

Your Agents → Phoenix (tracing) → Export traces → Pisama (failure detection)

Pisama ingests Phoenix trace exports for failure analysis via the built-in PhoenixImporter. (Exporting Pisama results back into Phoenix as spans is on the roadmap, not yet shipped.)

Import Phoenix Traces¶

Option 1: Export from Phoenix UI¶

1. In Phoenix, select the traces you want to analyze
2. Export as JSON (OTEL format)
3. Import into Pisama:

# CLI
pisama analyze phoenix_export.json

# Or via API
curl -X POST https://api.pisama.ai/api/v1/traces \
  -H "Authorization: Bearer $PISAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @phoenix_export.json

Option 2: Bulk Import¶

For historical analysis of many traces:

curl -X POST https://api.pisama.ai/api/v1/import-jobs \
  -H "Authorization: Bearer $PISAMA_API_KEY" \
  -F "file=@phoenix_traces.json" \
  -F "format=phoenix"

Monitor import progress:

curl https://api.pisama.ai/api/v1/import-jobs \
  -H "Authorization: Bearer $PISAMA_API_KEY"

Option 3: Python SDK¶

from pisama import analyze

# Analyze a Phoenix JSON export directly
result = analyze("phoenix_export.json")

for issue in result.issues:
    print(f"[{issue.type}] {issue.summary} (severity: {issue.severity})")
    print(f"  Agent: {issue.agent_id}")
    print(f"  {issue.recommendation}")

Export Results to Phoenix¶

Framework Auto-Detection¶

When importing Phoenix traces, Pisama automatically detects the agent framework from OTEL gen_ai.system and gen_ai.provider.name semantic conventions:

Typical Workflow¶

1. Instrument your agents with Phoenix (one-line auto-instrumentation)
2. Run your agents — Phoenix captures all traces
3. Export traces from Phoenix (JSON or via API)
4. Analyze with Pisama — get failure classifications, severity scores, and fix recommendations
5. Review detection results in the Pisama dashboard or via the REST API

Why Both?¶

Phoenix is the best open-source observability platform. Pisama is the best open-source failure detection platform. Use both.

Supported Formats¶

The Phoenix importer handles:

• Phoenix JSON export: Native format from Phoenix UI export
• OTEL JSON (resourceSpans format): Standard OTEL trace export
• JSONL: Line-delimited JSON traces

All formats are auto-detected — just pass the file and Pisama figures out the format.