Instrumentação OpenTelemetry para o Copilot SDK

Suporte interno à telemetria

O SDK tem suporte interno para configurar o OpenTelemetry no processo da CLI e propagar o Contexto de Rastreamento W3C entre o SDK e a CLI. Forneça um TelemetryConfig ao criar o cliente para aderir:

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?;

Opções de TelemetryConfig

O campo de protocolo OTLP configura o exportador "otlp-http" da CLI para todos os sinais. Deixe-o não definido para usar o padrão da CLI ou defina-o como "http/protobuf" para exportar protobuf por HTTP.

Telemetria de habilidades e comando

O runtime segue as convenções semânticas de habilidade do GenAI refinando intervalos existentes execute_tool , não adicionando uma operação de habilidade separada. Um carregador é nomeado execute_tool skill {skill}. Um script ou recurso identificado sem ambiguidade é nomeado execute_tool {tool} {skill} {resource}, com um nome de recurso relativo à skill. Outros trechos de comando acrescentam o nome real conhecido do launcher.

• gen_ai.skill.name e gen_ai.skill.resource.name: disponível independentemente da captura de conteúdo
• gen_ai.skill.description e gen_ai.skill.source.uri: Exigir captura de conteúdo por meio de TelemetryConfig
• process.executable.name: o executável iniciado diretamente, como o inicializador de shell, não um token de comando adivinhado
• process.executable.path: um caminho absoluto conhecido; requer captura de conteúdo
• process.exit.code: um inteiro, incluindo zero, quando uma ferramenta de execução de comando relata um código de saída; códigos de saída indisponíveis e falhas antes da criação do processo são omitidos

As ferramentas de sondagem não herdam atributos de processo do comando que leem. As identidades executáveis em área restrita são omitidas quando o back-end da área restrita não as expõe. Um código de saída diferente de zero não implica que a própria ferramenta falhou. Definições de skills e listagens de diretório não são recursos de skill nomeados. As habilidades pré-carregadas produzem eventos de invocação sem um span de ferramenta fabricado. A preparação repetida do mesmo contexto da habilidade do agente selecionado emite um recibo; o conteúdo alterado ou a procedência emite outro. As sessões filho relatam seus próprios pré-carregamentos de forma independente. Os spans de comando separados identificam o supervisor Unix sh gerado diretamente ou o executável selecionado do Windows PowerShell.

Ferramentas personalizadas que substituem nomes integrados não herdam atributos nativos de habilidade ou processo. As habilidades visíveis e habilitadas ainda possuem recursos quando a invocação de modelo está desabilitada. A atribuição de script usa o comando post-hook e o diretório do shell selecionado; ele é omitido quando scripts de inicialização ou perfis tornam o contexto de execução incerto.

Embora as configurações de telemetria gerenciadas não sejam resolvidas, buffers de rastreamento pendentes só capturam fatos da ferramenta independentes da captura. Descrições, URIs de origem e caminhos executáveis observados antes que a política seja resolvida são omitidos, mesmo que a captura seja habilitada posteriormente. A política final rege a reexecução; o acompanhamento desabilitado ou cancelado descarta o buffer.

Estas são alterações de nome de telemetria interruptivas: use gen_ai.skill.name em vez de github.copilot.tool.parameters.skill_name ou github.copilot.skill.namee use gen_ai.skill.source.uri em vez de github.copilot.skill.path. Os valores de origem local são URIs de arquivo, não caminhos nus. O github.copilot.skill.invoked evento e seu conteúdo, categoria de origem, gatilho e campo de plug-in permanecem específicos do Copilot. O conteúdo da habilidade mantém seu capture gate existente.

Os atributos de habilidade e os refinamentos de span têm estabilidade de desenvolvimento; os atributos de processo têm estabilidade Release Candidate.

Propagação de contexto de traceamento

A maioria dos usuários não precisa disso. O TelemetryConfig acima é tudo o que você precisa para coletar os rastros da CLI. A propagação de contexto de rastreamento descrita nesta seção é um recurso avançado para os aplicativos que criam os seus próprios intervalos OpenTelemetry e querem que eles apareçam no mesmo rastreamento distribuído que os intervalos da CLI.

O SDK pode propagar o Contexto de Rastreamento W3C (traceparent/tracestate) em conteúdos JSON-RPC para que os intervalos do aplicativo e os intervalos da CLI estejam vinculados em um rastreamento distribuído. Isso é útil quando, por exemplo, você quer visualizar um span de "tratamento da chamada de ferramenta" no seu aplicativo, aninhado dentro do span "executar ferramenta" da CLI, ou mostrar a chamada do SDK como filha do seu span de tratamento da solicitação.

Para atribuição de custo junto com rastreamentos, assine os eventos assistant.usage e inspecione apiEndpoint (AssistantUsageApiEndpoint) para visualizar se uma interação usou Conclusões de Chat, Respostas ou Mensagens do Anthropic; consulte Eventos de sessão de streaming.

SDK → CLI (de saída)

Para Node.js, forneça uma função de onGetTraceContext callback nas opções do cliente. Isso só será necessário se o aplicativo já usar @opentelemetry/api e você quiser vincular seus intervalos com os intervalos da CLI. O SDK chama esse retorno de chamada antes de session.create, session.resume e session.send RPCs.

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: "..." }
  },
});

Para Python, Go e .NET, a injeção de contexto de rastreamento é automática quando a respectiva API OpenTelemetry/Activity está configurada— nenhum retorno de chamada é necessário.

CLI → SDK (de entrada)

Quando a CLI chama um manipulador de ferramenta, o traceparent e tracestate do span da CLI está disponível em todos os idiomas:

• Vá para: o campo ToolInvocation.TraceContext é um context.Context com o rastreamento já restaurado, use-o diretamente como pai dos seus spans.
• Python: o contexto de rastreamento é restaurado automaticamente no manipulador por meio de trace_context(), os spans filho têm automaticamente como pai o span da CLI.
• .NET: o contexto de rastreamento é restaurado automaticamente via: RestoreTraceContext()instâncias filhas de Activity são associadas automaticamente como filhas ao span da CLI.
• Node.js: Como o SDK não tem dependência do OpenTelemetry, traceparent e tracestate são passados como strings brutas no objeto ToolInvocation. Restaure o contexto manualmente, se necessário:

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

Dependências por idioma

References

• Convenções Semânticas do OpenTelemetry GenAI
• Convenções semânticas do OPENTelemetry MCP
• OpenTelemetry Python SDK
• documentação do SDK Copilot