pi-phoenix-otel

Pi coding agent extension that streams OpenTelemetry GenAI traces to Arize Phoenix. Zero dependencies.

Packages

Package details

extension

Install pi-phoenix-otel from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-phoenix-otel
Package
pi-phoenix-otel
Version
0.3.0
Published
Oct 21, 2026
Downloads
397/mo · 42/wk
Author
lalitmadan
License
MIT
Types
extension
Size
57.3 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./extensions"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-phoenix-otel

Pi package

See everything your pi coding agent does, traced in Arize Phoenix. Every prompt, tool call, token, and cost — as a queryable trace waterfall.

Zero dependencies. No install scripts. One auditable file.

Install

pi install npm:pi-phoenix-otel

Restart pi (or run /reload).

Quick start

  1. Start Phoenix locally:

    uvx arize-phoenix serve     # UI at http://localhost:6006

  2. Send a message in pi. Traces land in the pi project automatically.

Phoenix not running? Use /otel-start and the extension launches it for you and waits until it's healthy.

What you get

One trace per session by default:

fix the login bug              (session root, CHAIN)
├── pi.run 1 · fix the login bug
│   ├── pi.turn 0        (tokens, cost, model)
│   │   ├── execute_tool read
│   │   └── execute_tool edit
│   └── pi.turn 1
├── pi.run 2 · now add caching
│   └── pi.turn 0 ── execute_tool bash
└── ...

Each trace captures:

  • Runs — prompts (including steers), final responses
  • Turns — tokens, cache reads, reasoning tokens, model, finish reason, cost
  • Tool calls — name, arguments, result, errors, duration

Spans use OpenInference/GenAI conventions, so Phoenix renders proper LLM and Tool panels. A clickable phoenix ↗ link in the status bar opens the session in Phoenix.

Configuration

Optional config at ~/.pi/agent/phoenix-otel.config.json:

{
	"endpoint": "http://localhost:6006/v1/traces",
	"service": "pi-coding-agent",
	"project": "my-project",
	"apiKey": "",
	"captureContent": true,
	"trace": "session",
	"maxTextBytes": 0,
	"maxToolResultBytes": 0,
	"maxParamsBytes": 0,
	"maxSystemPromptBytes": 0,
	"maxMessagesJsonBytes": 0,
	"maxJsonDepth": 0,
	"maxJsonItems": 0
}
Key Default Description
endpoint http://localhost:6006/v1/traces OTLP/HTTP endpoint
service pi-coding-agent service.name resource attribute
project repo name Phoenix project. Defaults to the enclosing git repository's directory name (pi outside a repo).
apiKey unset Sent as Authorization: Bearer … for Phoenix Cloud or auth proxies
captureContent true false = metadata-only (no prompt/response/tool text)
trace session session = one trace per session · run = one trace per prompt
maxTextBytes 0 (unlimited) Byte budget for prompts/responses.
maxToolResultBytes 0 (unlimited) Byte budget for tool arguments and results.
maxParamsBytes 0 (unlimited) Byte budget for invocation parameters.
maxSystemPromptBytes 0 (unlimited) Byte budget for the system prompt.
maxMessagesJsonBytes 0 (unlimited) Byte budget for the full input transcript; when capped, older turns are dropped.
maxJsonDepth 0 (unlimited) Nested-JSON depth cap for structured values.
maxJsonItems 0 (unlimited) Arrays/objects per JSON level.

A project-local .pi/phoenix-otel.config.json overrides only the keys it sets. Environment variables override both:

PHOENIX_OTEL_ENDPOINT, PHOENIX_SERVICE_NAME, PHOENIX_PROJECT, PHOENIX_API_KEY, PHOENIX_TRACE, PHOENIX_CAPTURE_CONTENT (0/false/no/off disables capture), PHOENIX_OTEL_ENABLED=0 (no-op mode).

Budgets are unlimited by default. To cap them, set maxTextBytes, maxToolResultBytes, maxParamsBytes, maxSystemPromptBytes, maxMessagesJsonBytes, maxJsonDepth, or maxJsonItems to a positive value (or use the matching PHOENIX_MAX_* env vars). 0 means unlimited.

When a cap does apply, cut text ends with …[+N bytes] so truncated content is never mistaken for complete content. If an export batch exceeds 4 MiB, the extension warns once with a hint to set a cap.

Commands

Command Action
/otel-start Start Phoenix in the background via uvx
/otel-status Show server, endpoint, project, and capture status
/otel-flush Flush pending spans now

Privacy

  • Zero dependencies — no supply-chain surface, one auditable source file.
  • No install-time code — runs only when pi loads it.
  • Local-first — spans are only sent to the endpoint you configure. Nothing else leaves your machine.
  • Content capture is on by default. Prompts, responses, and tool results can contain sensitive material. Set "captureContent": false for metadata-only tracing.
  • HTTPS is not enforced — use an HTTPS endpoint for anything non-local.

Requirements

License

MIT