$ cat ~/map/pi-otel.md

pi-otel

OpenTelemetry instrumentation for pi — hierarchical GenAI traces, flamegraphs, and OTLP or file exporters.

extensions✓ Sep 8

## TL;DR

An OpenTelemetry instrumentation extension for pi: hooks the extension lifecycle events into hierarchical GenAI-conformant traces, with waterfall flamegraphs separating LLM time-to-first-token from tool execution time.

## Key points

• $Hooks Pi's native lifecycle events — agent_start/end, turn_start/end, before_provider_request, message_end, tool_execution_start/end — into hierarchical traces: agent_run → turn → gen_ai.chat → tool spans.
• $Follows OpenTelemetry GenAI semantic conventions (gen_ai.system, gen_ai.request.model, usage token attributes including cache-read tokens).
• $Waterfall flamegraphs pinpoint LLM time-to-first-token versus tool execution time; tool spans capture duration, error status, and output byte sizes.
• $Three exporters: OTLP/HTTP for Jaeger, Langfuse, Arize Phoenix, SigNoz, OpenLIT, or an OTel Collector; JSON spans appended to .pi/traces.jsonl; or a pretty-printed console stream.
• $Defensive error boundaries ensure telemetry never crashes or interrupts the pi session; permanent installs go through pi install against a local checkout (global, or project-local with -l), with an ad-hoc single-session load documented.

## FAQ

## References

• README ↗

Last updated: Sep 8, 2026