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. Informe 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, 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?;

Opções de TelemetryConfig

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 aplicativos que criam 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 ver 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 ver se uma interação usou Chat Completions, Responses ou Anthropic Messages; 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 traceparentspantracestate da CLI está disponível em todos os idiomas:

• Go: 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 { 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();
      }
    })
  );
});

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