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.

Telemetría de aptitudes y dominio

El tiempo de ejecución sigue las convenciones semánticas de skill de GenAI refinando los spans existentes execute_tool, sin añadir una operación de skill independiente. Un cargador se denomina execute_tool skill {skill}. Un recurso o script identificados inequívocamente se denomina execute_tool {tool} {skill} {resource}, con un nombre de recurso relativo a la habilidad. Otros segmentos de comando anexan el nombre real del lanzador conocido.

• gen_ai.skill.name y gen_ai.skill.resource.name: disponible independientemente de la captura de contenido
• gen_ai.skill.description y gen_ai.skill.source.uri: requieren la captura de contenido a través de TelemetryConfig
• process.executable.name: el ejecutable iniciado directamente, como el iniciador de shell, no un token de comando adivinado.
• process.executable.path: ruta absoluta conocida; requiere la captura de contenido
• process.exit.code: un entero, incluido el cero, cuando una herramienta que ejecuta comandos informa de un código de salida; se omiten las salidas no disponibles y los fallos antes de iniciar el proceso

Las herramientas de sondeo no heredan atributos de proceso del comando que leen. Las identidades ejecutables de espacio aislado se omiten cuando el back-end del espacio aislado no los expone. Una salida distinta de cero no implica que la propia herramienta haya fallado. Las definiciones de aptitudes y los listados de directorios no se denominan recursos de aptitud. Las habilidades precargadas generan eventos de invocación sin un tramo de herramienta sintético. La preparación repetida del mismo contexto de habilidad del agente seleccionado emite un recibo; el contenido o el origen modificados emiten otro. Las sesiones secundarias notifican sus propias precargas de forma independiente. Los segmentos de comandos independientes identifican el supervisor de Unix sh iniciado directamente o el ejecutable seleccionado de Windows PowerShell.

Las herramientas personalizadas que sobrescriben los nombres predefinidos no heredan atributos nativos de habilidades o procesos. Las habilidades habilitadas y visibles siguen siendo propietarias de recursos cuando la invocación del modelo está deshabilitada. La atribución de scripts usa el comando post-hook y el directorio del shell seleccionado; se omite cuando los scripts de inicio o los perfiles hacen que el contexto de ejecución resulte incierto.

Aunque la configuración de telemetría administrada no está resuelta, los búferes de seguimiento pendientes solo capturan datos de herramientas independientes de la captura. Las descripciones, los URI de origen y las rutas de acceso ejecutables observados antes de que se resuelva la directiva se omiten, incluso si la captura se habilita más adelante. La directiva final rige la repetición; el seguimiento deshabilitado o cancelado descarta el búfer.

Estos son cambios de ruptura en los nombres de telemetría: use gen_ai.skill.name en lugar de github.copilot.tool.parameters.skill_name o github.copilot.skill.name, y use gen_ai.skill.source.uri en lugar de github.copilot.skill.path. Los valores de origen local son URI de archivo, no rutas sin esquema URI. El github.copilot.skill.invoked evento y sus campos de contenido, categoría de origen, desencadenador y complemento permanecen Copilot específicos. El contenido de la aptitud conserva su umbral de captura existente.

Los atributos de habilidad y los ajustes de tramos tienen estabilidad de desarrollo; los atributos de proceso tienen estabilidad de Release Candidate.

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