Pi OTEL Telemetry Extension

OpenTelemetry tracing and metrics for pi coding agent. Exports spans and counters for sessions, agent prompts, LLM turns, and tool executions.

Trace Structure

session                          (root span, entire session lifecycle)
├── agent.prompt                 (one per user message)
│   └── agent.turn               (one per LLM call + tool execution cycle)
│       ├── llm.request          (span event: before provider API call)
│       ├── tool.bash            (tool execution span)
│       ├── tool.read            (tool execution span)
│       └── tool.edit            (tool execution span)
├── model.changed                (span event on model switch)
└── session.compacted            (span event on compaction)

Metrics

Metric	Type	Labels	Description
pi.tokens.input	Counter	llm.model	Total input tokens consumed
pi.tokens.output	Counter	llm.model	Total output tokens produced
pi.tool.calls	Counter	tool.name	Total tool invocations
pi.tool.errors	Counter	tool.name	Total failed tool invocations
pi.tool.duration	Histogram (ms)	tool.name	Tool execution time
pi.turns	Counter	llm.model	Total LLM turns
pi.prompts	Counter	llm.model	Total user prompts
pi.session.duration	Histogram (s)	llm.model	Session duration

Trace Attributes

Session span

Attribute	Description
session.id	Session file path or "ephemeral"
session.cwd	Working directory
session.turns	Total turn count
session.tool_calls	Total tool calls
session.tokens.input	Total input tokens
session.tokens.output	Total output tokens
llm.model	Current model (provider/id)

Turn span

Attribute	Description
turn.index	Turn index within agent prompt
turn.number	Global turn number in session
turn.tool_results	Number of tool results
llm.usage.input_tokens	Tokens consumed (input)
llm.usage.output_tokens	Tokens produced (output)

Tool span

Attribute	Description
tool.name	Tool name (bash, read, edit, write, etc.)
tool.call_id	Unique tool call ID
tool.args_summary	Brief summary of arguments (truncated)
tool.is_error	Whether execution failed
tool.duration_ms	Execution time in milliseconds

Configuration

Environment Variable	Default	Description
OTEL_EXPORTER_OTLP_ENDPOINT	http://localhost:4318	OTLP HTTP endpoint
OTEL_SERVICE_NAME	pi-coding-agent	Service name in traces
PI_OTEL_ENABLED	true	Set to false to disable
PI_OTEL_DEBUG	false	Set to true to also log spans/metrics to console
OTEL_METRIC_EXPORT_INTERVAL	10000	Metric export interval in ms

Quick Start

With Jaeger (local)

# Start Jaeger with OTLP support
docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4318:4318 \
  jaegertracing/jaeger:2 \
  --set receivers.otlp.protocols.http.endpoint=0.0.0.0:4318

# Start pi (extension auto-discovered from ~/.pi/agent/extensions/)
pi

# Open Jaeger UI
open http://localhost:16686

With Grafana Tempo

OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4318 pi

Debug mode (console output)

PI_OTEL_DEBUG=true pi

Disable

PI_OTEL_ENABLED=false pi

Installation

Already installed at ~/.pi/agent/extensions/otel-telemetry/. The extension is auto-discovered by pi.

To reinstall dependencies:

cd ~/.pi/agent/extensions/otel-telemetry
npm install