Copilot SDK 的 OpenTelemetry 检测

内置遥测支持

SDK 内置支持在 CLI 进程中配置 OpenTelemetry，并在 SDK 和 CLI 之间传播 W3C 跟踪上下文。 创建客户端时，提供一个 TelemetryConfig 以选择启用：

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

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

from copilot import CopilotClient

client = CopilotClient(
    telemetry={
        "otlp_endpoint": "http://localhost:4318",
    },
)

client, err := copilot.NewClient(copilot.ClientOptions{
    Telemetry: &copilot.TelemetryConfig{
        OTLPEndpoint: "http://localhost:4318",
    },
})

var client = new CopilotClient(new CopilotClientOptions
{
    Telemetry = new TelemetryConfig
    {
        OtlpEndpoint = "http://localhost:4318",
    },
});

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.json.*;

var client = new CopilotClient(new CopilotClientOptions()
    .setTelemetry(new TelemetryConfig()
        .setOtlpEndpoint("http://localhost:4318"))
);

use github_copilot_sdk::{Client, ClientOptions, TelemetryConfig};

let client = Client::start(ClientOptions::new()
    .with_telemetry(TelemetryConfig::new()
        .with_otlp_endpoint("http://localhost:4318"))
).await?;

TelemetryConfig 选项

跟踪上下文传播

大多数用户不需要这样做。 以上 TelemetryConfig 是从 CLI 收集跟踪信息的全部所需。 本节中所述的跟踪上下文传播是一项 高级功能 ，适用于创建自己的 OpenTelemetry 范围的应用程序，并希望它们与 CLI 跨度出现在 相同的分布式跟踪 中。

SDK 可以在 JSON-RPC 有效负载上传播 W3C 跟踪上下文（traceparent/tracestate），以便应用程序范围和 CLI 跨度链接在一个分布式跟踪中。 例如，当你希望在应用中看到“处理工具调用”的 span 嵌套在 CLI 的“执行工具” span 内，或者将 SDK 调用显示为请求处理 span 的子 span 时，这会非常有用。

SDK → CLI （出站）

对于 Node.js，请在 onGetTraceContext 客户端选项中提供回调函数。 仅当应用程序已使用 @opentelemetry/api 并且想要将范围与 CLI 的跨度链接时，才需要这样做。 SDK 在 session.create、session.resume 和 session.send RPC 前调用此回调：

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; // { traceparent: "00-...", tracestate: "..." }
  },
});

对于 Python、Go 和 .NET，当配置相应的 OpenTelemetry/Activity API 时，跟踪上下文注入是自动的，无需回调。

CLI → SDK（传入）

当 CLI 调用工具处理程序时，CLI 的 span 中的 traceparent 和 tracestate 在所有语言中都可用：

• Go：ToolInvocation.TraceContext 字段是一个已恢复跟踪信息的 context.Context——可直接将其用作你的 span 的父级。
• Python：追踪上下文会通过 trace_context() 在处理程序周围自动恢复——子跨度会自动以 CLI 的跨度为父跨度。
• .NET：跟踪上下文会通过 RestoreTraceContext() 自动恢复——子 Activity 实例会自动关联到 CLI 的 span。
• Node.js：由于 SDK 没有 OpenTelemetry 依赖，traceparent 和 tracestate 会作为原始字符串通过 ToolInvocation 对象传递。 如果需要，请手动还原上下文：

import { propagation, context, trace } from "@opentelemetry/api";

session.registerTool(myTool, async (args, invocation) => {
  // Restore the CLI's trace context as the active context
  const carrier = {
    traceparent: invocation.traceparent,
    tracestate: invocation.tracestate,
  };
  const parentCtx = propagation.extract(context.active(), carrier);

  // Create a child span under the CLI's span
  const tracer = trace.getTracer("my-app");
  return context.with(parentCtx, () =>
    tracer.startActiveSpan("my-tool", async (span) => {
      try {
        const result = await doWork(args);
        return result;
      } finally {
        span.end();
      }
    })
  );
});

每种语言的依赖项

References

• OpenTelemetry GenAI 语义约定
• OpenTelemetry MCP 语义约定
• OpenTelemetry Python SDK
• Copilot SDK 文档