SDK OpenTelemetry

配置 runtime 追踪导出，并按语言连接应用与工具调用的 trace context。

This page has not been translated into English yet. The original Chinese version is shown below.

Copilot SDK 可以为 CLI runtime 配置 OpenTelemetry，并通过 JSON-RPC 传递 W3C Trace Context。只需要收集 runtime traces 时，配置 telemetry 即可；应用自己已经创建 spans、需要合成分布式 trace 时，再接入上下文传递。

配置导出

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  telemetry: {
    otlpEndpoint: "http://localhost:4318",
    otlpProtocol: "http/protobuf",
  },
});

这是本地 collector 地址示例，需有实际接收端。TypeScript TelemetryConfig 包含：

字段	含义
`otlpEndpoint`	OTLP HTTP endpoint
`otlpProtocol`	http/json 或 http/protobuf，作用于所有信号
`filePath`	JSON-lines trace 输出路径
`exporterType`	otlp-http 或 file
`sourceName`	instrumentation scope 名称
`captureContent`	是否采集消息内容

省略协议使用 CLI 默认，官方专题没有在这里固定该默认值。按数据需求决定是否采集消息内容，不把开启导出自动等同于必须保存 prompt 全文。

应用到 runtime 的上下文

Node.js SDK 自身不依赖 OpenTelemetry。应用使用 @opentelemetry/api 时，通过 onGetTraceContext 在 session.create、session.resume、session.send 前提供当前 traceparent/tracestate：

import { CopilotClient } from "@github/copilot-sdk";
import { propagation, context } from "@opentelemetry/api";

const client = new CopilotClient({
  telemetry: { otlpEndpoint: "http://localhost:4318" },
  onGetTraceContext: () => {
    const carrier: Record<string, string> = {};
    propagation.inject(context.active(), carrier);
    return carrier;
  },
});

这段代码要求应用已有相应库与 tracing 初始化。Python、Go、.NET 在各自 OpenTelemetry/Activity 已配置时自动注入；Java 依赖说明也明确 Java agent 或 SDK 配置后自动注入。不要为了所有语言看起来统一，额外臆造相同回调。

runtime 调用应用工具时

工具 handler 也能取得 runtime 的 trace context，使应用 span 成为执行工具 span 的子节点：

Go：ToolInvocation.TraceContext 已恢复为 context.Context。
Python：通过 trace_context() 在 handler 周围自动恢复。
.NET：通过 RestoreTraceContext() 恢复，子 Activity 归入父 trace。
Node.js：ToolInvocation 提供原始 traceparent、tracestate 字符串，应用需要时手动 extract 并在该上下文创建 span。

该页没有对每种语言都列出完全相同的入站恢复代码；未列出的细节以当前 SDK 类型为准。

依赖与用量关联

Python 官方提供 pip install copilot-sdk[telemetry]，Go 使用 go.opentelemetry.io/otel，.NET 使用内置 System.Diagnostics.Activity，Java 可添加 io.opentelemetry:opentelemetry-api。是否安装或启用完整 exporter 仍由宿主应用的观测方案决定。

将 trace 与用量关联时可订阅 assistant.usage，读取 apiEndpoint 区分 Chat Completions、Responses、Anthropic Messages。费用和配额口径见SDK 用量，trace 次数本身不是费用账本。