Instrumentación de OpenTelemetry para el SDK de Copilot

Compatibilidad con telemetría integrada

El SDK tiene compatibilidad integrada para configurar OpenTelemetry en el proceso de la CLI y propagar el contexto de seguimiento de W3C entre el SDK y la CLI. Proporcione un TelemetryConfig al crear el cliente para habilitarlo:

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

Opciones de TelemetryConfig

El campo de protocolo OTLP configura el exportador "otlp-http" de la CLI para todas las señales. Déjelo sin definir para usar el valor predeterminado de la CLI, o configúrelo como "http/protobuf" para exportar en formato protobuf a través de HTTP.

Propagación del contexto de rastreo

La mayoría de los usuarios no necesitan esto. La TelemetryConfig anterior es lo único que necesita para recopilar seguimientos desde la CLI. La propagación del contexto de seguimiento que se describe en esta sección es una característica avanzada para las aplicaciones que crean sus propios intervalos de OpenTelemetry y quieren que aparezcan en el mismo seguimiento distribuido que los intervalos de la CLI.

El SDK puede propagar el contexto de seguimiento de W3C (traceparent/tracestate) en cargas JSON-RPC para que las trazas de la aplicación y las trazas de la CLI estén vinculadas en un seguimiento distribuido. Esto resulta útil cuando, por ejemplo, desea ver un intervalo «controlar llamada a herramienta» de su aplicación anidado dentro del intervalo «ejecutar herramienta» de la CLI, o mostrar la llamada del SDK como elemento secundario del intervalo de control de solicitudes.

Para atribuir costes junto con los seguimientos, suscríbase a assistant.usageeventos e inspeccione apiEndpoint (AssistantUsageApiEndpoint) para comprobar si un turno utilizó Finalizaciones de chat, Respuestas o Mensajes de Anthropic; consulte TÍTULO AUTOMÁTICO.

SDK → CLI (de salida)

Para Node.js, proporcione una devolución de llamada onGetTraceContext en las opciones del cliente. Solo es necesario si la aplicación ya utiliza @opentelemetry/api y desea vincular los intervalos con los intervalos de la CLI. El SDK llama a esta devolución de llamada antes que a las session.create, session.resume y 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: "..." }
  },
});

Para Python, Go y .NET, la inyección del contexto de trazas es automática cuando está configurada la API correspondiente de OpenTelemetry/Activity; no se necesita ninguna función de callback.

CLI → SDK (entrante)

Cuando la CLI invoca un controlador de herramientas, traceparent y tracestate del tramo de la CLI están disponibles en todos los idiomas:

• Go: El campo ToolInvocation.TraceContext es un context.Context con la traza ya restaurada; úselo directamente como elemento principal para sus spans.
• Python: El contexto de seguimiento se restaura automáticamente alrededor del controlador mediantetrace_context(); los intervalos secundarios se vinculan automáticamente al intervalo de la CLI.
• .NET: El contexto de seguimiento se restaura automáticamente mediante RestoreTraceContext(); las instancias secundarias de Activity se vinculan automáticamente al intervalo de la CLI.
• Node.js: Dado que el SDK no tiene ninguna dependencia de OpenTelemetry, traceparent y tracestate se pasan como cadenas sin procesar en el objeto ToolInvocation. Restaure el contexto manualmente si es necesario:

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

Dependencias por lenguaje

References

• Convenciones semánticas de OpenTelemetry GenAI
• Convenciones semánticas de MCP de OpenTelemetry
• SDK de OpenTelemetry Python
• Documentación del SDK de Copilot