$ cat ~/map/pi-otel.md

pi-otel

pi 的 OTel 埋点：GenAI 追踪、火焰图，OTLP 与文件导出。

extensions✓ 9月8日

## 速览

pi 的 OpenTelemetry 埋点扩展：把扩展生命周期事件接入层级化的 GenAI 兼容追踪，火焰图将 LLM 首字延迟与工具执行时间分开呈现。

## 要点

• $挂接 Pi 的原生生命周期事件——agent_start/end、turn_start/end、before_provider_request、message_end、tool_execution_start/end——构建层级追踪：agent_run → turn → gen_ai.chat → 工具 span。
• $遵循 OpenTelemetry GenAI 语义约定（gen_ai.system、gen_ai.request.model，以及含缓存读取 token 在内的用量属性）。
• $瀑布式火焰图精确区分 LLM 首字延迟与工具执行耗时；工具 span 记录时长、错误状态与输出字节大小。
• $三种导出器：OTLP/HTTP 对接 Jaeger、Langfuse、Arize Phoenix、SigNoz、OpenLIT 或 OTel Collector；JSON span 追加到 .pi/traces.jsonl；或以美化格式输出到控制台。
• $防御性错误边界保证遥测绝不崩溃或打断 pi 会话；永久安装通过 pi install 指向本地检出（全局，或 -l 项目级），另有单次会话的临时加载方式。

## 常见问题

## 参考链接

• README ↗

最后更新: 2026年9月8日