跳转到主要内容

​
OpenTelemetry

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

​
基本使用方式

​
启用 CLI 进程的追踪

在 config/copilot.php 中添加 telemetry 设置，或直接通过选项指定。 
// config/copilot.php
'telemetry' => [
    'otlpEndpoint' => 'http://localhost:4318',
],
或直接指定。 
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\TelemetryConfig;

Copilot::useStdio([
    'telemetry' => new TelemetryConfig(
        otlpEndpoint: 'http://localhost:4318',
    )
]);

$response = Copilot::run(prompt: 'Hello');
直接使用 client 时： 
use Revolution\Copilot\Client;
use Revolution\Copilot\Types\TelemetryConfig;

$client = new Client([
    'telemetry' => new TelemetryConfig(
        otlpEndpoint: 'http://localhost:4318',
    ),
]);

​
TelemetryConfig 选项

选项说明
otlpEndpointOTLP HTTP 端点 URL
filePathJSON-lines 追踪输出的文件路径
exporterType"otlp-http" 或 "file"
sourceNameinstrumentation scope 名称
captureContent是否捕获消息内容（prompt、response）

​
W3C Trace Context 传播

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

​
自动传播（推荐）

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

​
自定义提供程序

如果想使用自己的追踪上下文获取逻辑： 
use Revolution\Copilot\Support\TraceContext;

TraceContext::useProvider(function (): array {
    return [
        'traceparent' => '00-traceid-spanid-01',
        'tracestate' => 'vendor=value',
    ];
});

​
SDK → CLI（出站）

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

​
CLI → SDK（入站）

当 CLI 调用工具时，工具处理器的 $invocation 数组中会包含追踪上下文。 
$session->registerTools([
    [
        'name' => 'my-tool',
        'description' => 'My custom tool',
        'handler' => function (array $args, array $invocation) {
            // 来自 CLI span 的追踪上下文
            $traceparent = $invocation['traceparent'] ?? null;
            $tracestate = $invocation['tracestate'] ?? null;

            // 如果安装了 open-telemetry/api
            // 上下文会自动恢复，
            // 这里创建的 span 会成为 CLI span 的子级

            return 'result';
        },
    ],
]);
当安装了 open-telemetry/api 时，工具处理器执行期间的 OpenTelemetry 上下文会自动关联到 CLI 的 span。无需显式使用 traceparent。

​
依赖

包用途
open-telemetry/api自动 Trace Context 传播（suggest，可选）
open-telemetry/sdk追踪数据的导出
open-telemetry/api 包含在 composer.json 的 suggest 中。即使没有安装，SDK 本身也可以正常工作。
最新信息请参考 GitHub 仓库。
最后修改于 2026年7月13日

相关主题

流式事件