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

TelemetryConfig-Optionen

Das Feld für das OTLP-Protokoll konfiguriert den "otlp-http"-Exporter der CLI für alle Signale. Lassen Sie es nicht gesetzt, um die CLI-Standardeinstellung zu verwenden, oder setzen Sie es auf "http/protobuf", um Protobuf über HTTP zu exportieren.

Skill- und Befehlstelemetrie

Die Laufzeit folgt den GenAI-Skill-Semantikkonventionen durch Verfeinern vorhandener execute_tool Spans, ohne einen separaten Skill-Vorgang hinzuzufügen. Ein Loader heißt execute_tool skill {skill}. Eine eindeutig identifizierte Ressource oder ein Skript wird mit einem skill-relativen Ressourcennamen benannt execute_tool {tool} {skill} {resource}. Andere Befehlsspannen fügen den tatsächlichen Namen des bekannten Launchers an.

• gen_ai.skill.name und gen_ai.skill.resource.name: Unabhängig von der Inhaltserfassung verfügbar
• gen_ai.skill.description und gen_ai.skill.source.uri: Anfordern der Inhaltserfassung über TelemetryConfig
• process.executable.name: Die direkt gestartete ausführbare Datei, z. B. der Shell-Launcher, kein erratenes Befehlstoken
• process.executable.path: Ein absoluter bekannter Pfad; erfordert inhaltserfassung
• process.exit.code: Eine ganze Zahl, einschließlich Null, wenn ein Befehlsausführungstool einen Exit meldet; nicht verfügbare Exit-Codes und Fehler vor dem Spawn werden weggelassen.

Abfragetools erben keine Prozessattribute von dem Befehl, den sie lesen. Sandbox-Executable-Identitäten werden weggelassen, wenn das Sandbox-Backend sie nicht verfügbar macht. Ein Nonzero-Exit bedeutet nicht, dass das Tool selbst fehlgeschlagen ist. Qualifikationsdefinitionen und Verzeichnisauflistungen werden nicht als Skill-Ressourcen bezeichnet. Vorgeladene Fähigkeiten erzeugen Aufrufereignisse ohne einen künstlich erzeugten Tool-Span. Die wiederholte Vorbereitung desselben Kontexts der Qualifikation des ausgewählten Agenten erstellt einen Beleg; geänderte Inhalte oder eine geänderte Provenienz erstellen einen weiteren Beleg. Untergeordnete Sitzungen melden ihre eigenen Preloads unabhängig voneinander. Getrennte Befehlsspannen identifizieren den direkt gestarteten Unix-sh-Supervisor oder die ausgewählte ausführbare Windows-PowerShell-Datei.

Benutzerdefinierte Tools, die vordefinierte Namen außer Kraft setzen, erben kein systemeigenes Skill-Attribut oder Prozessattribute. Sichtbare, aktivierte Fähigkeiten besitzen weiterhin Ressourcen, wenn der Aufruf des Modells deaktiviert ist. Die Skriptzuordnung verwendet den Post-Hook-Befehl und das Verzeichnis der ausgewählten Shell; sie wird weggelassen, wenn Startskripts oder Profile den Ausführungskontext unsicher machen.

Während verwaltete Telemetrieeinstellungen ungeklärt sind, erfassen ausstehende Nachverfolgungspuffer nur erfassungsunabhängige Tooldaten. Beschreibungen, Quell-URIs und ausführbare Pfade, die beobachtet wurden, bevor die Richtlinie wirksam wird, werden weggelassen, auch wenn die Erfassung später aktiviert wird. Die endgültige Richtlinie regelt die Wiederholung; deaktiviertes oder abgebrochenes Tracking verwirft den Puffer.

Dies sind inkompatible Änderungen an Telemetrienamen: Verwenden Sie gen_ai.skill.name anstelle von github.copilot.skill.name oder github.copilot.tool.parameters.skill_name, und verwenden Sie gen_ai.skill.source.uri anstelle von github.copilot.skill.path. Lokale Quellwerte sind Datei-URIs, keine baren Pfade. Das github.copilot.skill.invoked Ereignis und seine Inhalts-, Quellkategorie-, Trigger- und Plug-In-Felder bleiben Copilot-spezifisch. Skill-Inhalte behalten ihre bestehende Erfassungssperre bei.

Die Skill-Attribute und Span-Verfeinerungen haben Entwicklungsstabilität; die Prozessattribute haben Release-Candidate-Stabilität.

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.

Für die Kostenzuordnung zusammen mit Traces abonnieren Sie die assistant.usage-Events und prüfen Sie apiEndpoint (AssistantUsageApiEndpoint), um festzustellen, ob ein Turn Chatvervollständigungen, Antworten oder Anthropic Messages verwendet hat; siehe Ereignisse einer Streaming-Sitzung.

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 übergeordnet.
• .NET: Der Trace-Kontext wird automatisch über RestoreTraceContext() wiederhergestellt – untergeordnete Activity-Instanzen werden automatisch dem CLI-Span übergeordnet.
• 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 { 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] });

Abhängigkeiten pro Sprache

Referenzen

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