Инструментация OpenTelemetry для Copilot SDK

Встроенная поддержка телеметрии

SDK поддерживает встроенную поддержку настройки OpenTelemetry на процессе CLI и распространения W3C Trace Context между SDK и CLI. Указывайте 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.CopilotClient;
import com.github.copilot.rpc.*;

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 spans и хотят, чтобы они отображались в той же распределённой трассе , что и spans CLI.

SDK может передавать W3C Trace Context (traceparent/tracestate) на JSON-RPC полезных нагрузках, чтобы span-и вашего приложения и CLI были связаны в одну распределённую трассу. Это полезно, когда, например, вы хотите увидеть span «handle tool call» в вашем приложении, встроенный в span «execute tool» CLI, или показывать SDK-вызов как дочерний span обработки запросов.

Для атрибуции стоимости вместе с трассами подписывайтесь на события assistant.usage и проверяйте apiEndpoint (AssistantUsageApiEndpoint), чтобы узнать, использовал ли ход завершения чата, ответы или Anthropic сообщения; см. События потоковых сессий.

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 инъекция контекста trace происходит автоматически при настройке соответствующего API OpenTelemetry/Activity — обратный вызов не требуется.

CLI → SDK (входящий)

Когда CLI вызывает обработчик инструментов, traceparent диапазон и tracestate из CLI доступны во всех языках:

• Вперед: поле ToolInvocation.TraceContext уже context.Context восстановлено с трассировкой — используйте его напрямую как родителя для ваших пролётов.
• Python: Контекст трассировки автоматически восстанавливается вокруг обработчика через trace_context() — дочерние спыны автоматически прикрепляются к спану CLI.
• .NET: Трассирующий контекст автоматически восстанавливается через RestoreTraceContext() — дочерние экземпляры Activity автоматически связываются с span CLI.
• Node.js: Поскольку SDK не зависит traceparent от OpenTelemetry и 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();
      }
    })
  );
});

Зависимости по языкам

Ссылки

• Семантические конвенции OpenTelemetry GenAI
• Семантические конвенции MCP OpenTelemetry
• OpenTelemetry Python SDK
• Copilot документация SDK