OpenTelemetry-Instrumentierung für Copilot SDK

Integrierte Telemetrieunterstützung

Das SDK bietet integrierte Unterstützung für die Konfiguration von OpenTelemetry im CLI-Prozess sowie für die Weitergabe des W3C Trace Context zwischen dem SDK und der CLI. Geben Sie beim Erstellen des Clients ein TelemetryConfig an, um die Teilnahme zu aktivieren:

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.sdk.CopilotClient;
import com.github.copilot.sdk.json.*;

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

TelemetryConfig-Optionen

Ablaufverfolgungskontext-Propagierung

Die meisten Benutzer benötigen dies nicht. Das TelemetryConfig oben ist alles, was Sie benötigen, um Ablaufverfolgungen von der CLI zu sammeln. Die in diesem Abschnitt beschriebene Weitergabe des Trace-Kontexts ist eine erweiterte Funktion für Anwendungen, die ihre eigenen OpenTelemetry-Spans erstellen und möchten, dass diese im selben verteilten Trace wie die Spans der CLI erscheinen.

Das SDK kann den W3C-Ablaufverfolgungskontext (traceparent/tracestate) an JSON-RPC Nutzlasten weitergeben, sodass die Spanne Ihrer Anwendung und die Spanne der CLI in einer verteilten Ablaufverfolgung verknüpft sind. Dies ist nützlich, wenn Sie z. B. in Ihrer App einen „Handle tool call“-Span sehen möchten, der innerhalb des „Execute tool“-Spans der CLI verschachtelt ist, oder wenn der SDK-Aufruf als untergeordnetes Element Ihres Spans zur Anforderungsverarbeitung angezeigt werden soll.

SDK → CLI (ausgehend)

Geben Sie in den Client-Optionen für Node.js einen onGetTraceContext Callback an. Dies ist nur erforderlich, wenn Ihre Anwendung bereits @opentelemetry/api verwendet und Sie Ihre Spannen mit den Spannen der CLI verknüpfen möchten. Das SDK ruft diesen Rückruf vor session.create, session.resume und session.send RPCs auf:

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

Für Python****Go und .NET wird die Ablaufverfolgungskontexteinfügung automatisch durchgeführt, wenn die entsprechende OpenTelemetry/Activity-API konfiguriert ist– es ist kein Rückruf erforderlich.

CLI → SDK (eingehend)

Wenn die CLI einen Toolhandler aufruft, sind die traceparent und tracestate aus der CLI-Spanne in allen Sprachen verfügbar:

• Go: Das ToolInvocation.TraceContext-Feld ist ein context.Context mit dem bereits rekonstruierten Trace – verwenden Sie es direkt als übergeordnetes Objekt für Ihre Spans.
• Python: Der Trace-Kontext wird über trace_context() automatisch um den Handler herum wiederhergestellt – untergeordnete Spans werden automatisch dem Span der CLI untergeordnet.
• .NET: Der Trace-Kontext wird automatisch über RestoreTraceContext() wiederhergestellt – untergeordnete Activity-Instanzen werden automatisch dem CLI-Span untergeordnet.
• Node.js: Da das SDK keine OpenTelemetry-Abhängigkeit hat, werden traceparent und tracestate im ToolInvocation-Objekt als rohe Zeichenfolgen übergeben. Stellen Sie den Kontext bei Bedarf manuell wieder her:

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

Abhängigkeiten pro Sprache

Referenzen

• OpenTelemetry GenAI Semantic Conventions
• OpenTelemetry MCP Semantic Conventions
• OpenTelemetry Python SDK
• Copilot SDK-Dokumentation