Инструментация 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 := 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

Поле протокола OTLP настраивает "otlp-http" экспортера CLI для всех сигналов. Оставьте его неустановленным, чтобы использовать CLI по умолчанию, или поставьте на "http/protobuf" экспорт protobuf через HTTP.

Навык и телеметрия команд

Среда выполнения следует семантике навыка GenAI путем уточнения существующих execute_tool диапазонов, а не добавления отдельной операции навыка. Загрузчик называется execute_tool skill {skill}. Однозначно определяемый ресурс или скрипт называется execute_tool {tool} {skill} {resource}с именем относительного навыка. Другие команды охватывают добавление фактического имени известного средства запуска.

• gen_ai.skill.name и gen_ai.skill.resource.name: доступно независимо от записи содержимого
• gen_ai.skill.description и gen_ai.skill.source.uri: требуется запись содержимого с помощью TelemetryConfig
• process.executable.name: непосредственно запущенный исполняемый файл, например средство запуска оболочки, а не угаданный маркер команды
• process.executable.path: абсолютный известный путь; требуется запись содержимого
• process.exit.code: целое число, включая ноль, когда средство выполнения команд сообщает о выходе; недоступные выходы и сбои, которые предварительно создаются, опущены

Средства опроса не наследуют атрибуты процесса из команды, с которой они считываются. Изолированные исполняемые удостоверения опущены, если серверная часть песочницы не предоставляет их. Ненулевой выход не означает, что сам инструмент завершился сбоем. Определения навыков и списки каталогов не называются ресурсами навыка. Предварительно загруженные навыки создают события вызова без сложенного диапазона инструментов. Повторная подготовка одного контекста навыка выбранного агента выдает одну квитанцию; измененное содержимое или происхождение выдает другое. Дочерние сеансы сообщают о своих предзагрузках независимо. Отсоединяемые команды определяют непосредственно спеченного руководителя Unix sh или выбранные Windows исполняемый файл PowerShell.

Пользовательские средства, которые переопределяют встроенные имена, не наследуют собственные атрибуты навыка или процесса. Видимые, включенные навыки по-прежнему имеют собственные ресурсы при отключении вызова модели. В скрипте attribution используется команда post-hook и каталог выбранной оболочки; Он опущен, когда скрипты или профили запуска делают контекст выполнения неопределенным.

Хотя параметры управляемой телеметрии не разрешены, ожидающие буферы отслеживания только факты средства, независимые от записи. Описания, исходные URI и пути исполняемых файлов, наблюдаемые до устранения политики, опущены, даже если запись будет включена позже. Окончательная политика управляет воспроизведением; Отключено или отменено отслеживание удаляет буфер.

Это критически важные изменения в имени телеметрии: используйте gen_ai.skill.name``gen_ai.skill.source.uri вместо github.copilot.skill.name``github.copilot.tool.parameters.skill_name него или вместо негоgithub.copilot.skill.path. Локальные исходные значения — это URI файлов, а не путь к открытым. События и его содержимоеgithub.copilot.skill.invoked, исходные категории, триггеры и поля подключаемых модулей остаются Copilot. Содержимое навыка сохраняет существующий шлюз захвата.

Атрибуты навыка и уточнения диапазона имеют стабильность разработки; Атрибуты процесса имеют стабильность кандидата выпуска.

Распространение контекста следов

Большинству пользователей это не нужно. Вышеописанное — всё, 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 { defineTool } from "@github/copilot-sdk";
import { propagation, context, trace } from "@opentelemetry/api";

const myTool = defineTool("my-tool", {
  description: "Do work",
  handler: 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();
        }
      })
    );
  },
});

// Tool handlers are registered when the session is created.
const session = await client.createSession({ tools: [myTool] });

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

Ссылки

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