跳转到主要内容

OpenTelemetry

Copilot CLI 内置了 OpenTelemetry 的 tracing 功能。只需在 SDK 侧进行配置,就可以收集 CLI 进程的追踪数据。

基本使用方式

启用 CLI 进程的追踪

config/copilot.php 中添加 telemetry 设置,或直接通过选项指定。
或直接指定。
直接使用 client 时:

TelemetryConfig 选项

W3C Trace Context 传播

对大多数用户来说不需要该功能。仅通过上面的 TelemetryConfig 即可收集 CLI 的追踪。以下是当你在应用侧创建自己的 OpenTelemetry span,并希望与 CLI 的 span 在同一分布式追踪中显示时的高级功能。
SDK 会向 session.createsession.resumesession.send 的 JSON-RPC 请求中自动注入 W3C Trace Context(traceparent/tracestate)。

自动传播(推荐)

只需安装 open-telemetry/api 包,追踪上下文就会被自动传播。
安装之后无需特殊设置,应用的 span 与 CLI 的 span 就会被关联到同一个分布式追踪。

自定义提供程序

如果想使用自己的追踪上下文获取逻辑:

SDK → CLI(出站)

以下 RPC 调用会自动注入 traceparent/tracestate
  • session.create — 创建会话时
  • session.resume — 恢复会话时
  • session.send — 发送消息时

CLI → SDK(入站)

当 CLI 调用工具时,工具处理器的 $invocation 数组中会包含追踪上下文。
当安装了 open-telemetry/api 时,工具处理器执行期间的 OpenTelemetry 上下文会自动关联到 CLI 的 span。无需显式使用 traceparent

依赖

open-telemetry/api 包含在 composer.jsonsuggest 中。即使没有安装,SDK 本身也可以正常工作。
最新信息请参考 GitHub 仓库
最后修改于 2026年7月18日

相关主题

流式事件