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 → Phoenix (results as spans)

Pisama supports bidirectional Phoenix integration:

• Import: Ingest Phoenix trace exports for failure analysis
• Export: Send Pisama detection results back to Phoenix as OTEL spans

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://pisama-api.fly.dev/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://pisama-api.fly.dev/api/v1/import-jobs \
  -H "Authorization: Bearer $PISAMA_API_KEY" \
  -F "file=@phoenix_traces.json" \
  -F "format=phoenix"

Monitor import progress:

curl https://pisama-api.fly.dev/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¶

Pisama can export calibration runs and detection results as OTEL spans that appear in the Phoenix UI:

from pisama.exporters import PhoenixExporter

exporter = PhoenixExporter(phoenix_url="http://localhost:6006")
exporter.export_calibration_run(run_id=10)

This creates spans in Phoenix showing:

• Detection results per trace (pass/fail, failure type, severity)
• Detector performance metrics (F1, precision, recall)
• Cost and latency per detection tier

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 Pisama dashboard or exported back to Phoenix

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.