Instrumentação OpenTelemetry para o Copilot SDK

          SDK do Copilot está atualmente em versão prévia técnica. A funcionalidade e a disponibilidade estão sujeitas a alterações.

          SDK do GitHub Copilot possui suporte nativo para configurar o OpenTelemetry no processo da CLI e para propagar o contexto de rastreamento W3C entre o SDK e a CLI.

Para obter exemplos em Python, Go e .NET, consulte o github/copilot-sdkrepositório.

Suporte interno à telemetria

Para aceitar a telemetria, forneça um TelemetryConfig ao criar o cliente:

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  telemetry: {
    otlpEndpoint: "http://localhost:4318",
  },
});

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  telemetry: {
    otlpEndpoint: "http://localhost:4318",
  },
});

Opções de TelemetryConfig

          `"otlp-http"` ou `"file"` |

| Nome de origem | sourceName | Nome do escopo da instrumentação | | Capturar conteúdo | captureContent | Se o conteúdo da mensagem deve ser capturado |

Propagação de contexto de traceamento

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ê deseja mostrar a chamada do SDK como um filho do seu intervalo de tratamento de solicitações.

Para obter um diagrama de sequência detalhado do fluxo de sessão, consulte o github/copilot-sdkrepositório.

SDK para CLI (saída)

Forneça um onGetTraceContext retorno de chamada 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: "..." }
  },
});

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

CLI para SDK (entrada de dados)

Quando a CLI invoca um manipulador de ferramentas, o traceparent e tracestate do intervalo da CLI estão disponíveis. Como o SDK não tem nenhuma dependência OpenTelemetry, elas são passadas como cadeias de caracteres brutas no ToolInvocation objeto. 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();
      }
    })
  );
});

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

Leitura adicional

•         [Convenções semânticas do OpenTelemetry GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/) na documentação do OpenTelemetry
  

•         [Convenções semânticas do OPENTelemetry MCP](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/) na documentação do OpenTelemetry
  

•         [SDK do Python OpenTelemetry](https://opentelemetry.io/docs/instrumentation/python/) na documentação do OpenTelemetry