Copilot SDK 的 OpenTelemetry 插装

注意

Copilot SDK 目前处于公开预览阶段。功能和可用性可能会更改。

GitHub Copilot SDK 内置支持在 CLI 进程上配置 OpenTelemetry，并在 SDK 与 CLI 之间传播 W3C 跟踪上下文。

有关 Python、Go 和 .NET 示例，请参阅 github/copilot-sdk 仓库。对于 Java，请参阅 github/copilot-sdk-java 仓库。

内置遥测支持

要加入遥测，请在创建客户端时提供 TelemetryConfig。

TypeScript

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

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

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

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

TelemetryConfig 选项

选项	Node.js	描述
OTLP 端点	`otlpEndpoint`	OTLP HTTP 端点 URL
文件路径	`filePath`	JSON 行日志（trace）输出的文件路径
导出器类型	`exporterType`	`"otlp-http"` 或 `"file"`
来源名称	`sourceName`	插装范围名称
捕获内容	`captureContent`	是否捕获消息内容

跟踪上下文传播

注意

大多数用户不需要此功能。上述 TelemetryConfig 已足以从 CLI 收集跟踪。跟踪上下文传播是为那些创建自己 OpenTelemetry span 并希望它们出现在与 CLI span 同一分布式跟踪中的高级功能。

SDK 可以在 JSON-RPC 负载上传播 W3C 跟踪上下文（traceparent/tracestate），以便您的应用程序的 span 与 CLI 的 span 关联在同一个分布式跟踪中。例如，当您希望将 SDK 调用显示为请求处理 span 的子 span 时，这非常有用。

有关会话流的详细顺序图，请参阅 github/copilot-sdk 仓库。

SDK 到 CLI（出站）

在客户端选项中提供 onGetTraceContext 回调。仅在您的应用程序已经使用 @opentelemetry/api 并希望将您的 span 与 CLI 的 span 关联时才需要。SDK 在 session.create、session.resume 和 session.send RPC 之前调用此回调。

TypeScript

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

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

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

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

CLI 到 SDK（入站）

当 CLI 调用工具处理程序时，CLI span 的 traceparent 和 tracestate 可用。由于 SDK 没有 OpenTelemetry 依赖，这些会作为原始字符串放在 ToolInvocation 对象上。如果需要，请手动恢复上下文。

TypeScript

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();
      }
    })
  );
});

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();
      }
    })
  );
});

谁可以使用此功能？

本文内容

内置遥测支持

TelemetryConfig 选项

跟踪上下文传播

SDK 到 CLI（出站）

CLI 到 SDK（入站）

延伸阅读