Instrumentation OpenTelemetry pour le Kit de développement logiciel (SDK) Copilot

Prise en charge de la télémétrie intégrée

Le Kit de développement logiciel (SDK) prend en charge la configuration d’OpenTelemetry sur le processus CLI et la propagation du contexte de trace W3C entre le Kit de développement logiciel (SDK) et l’interface CLI. Fournissez TelemetryConfig lors de la création du client pour activer cette option :

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

Options de configuration de télémétrie

Le champ du protocole OTLP configure l’exportateur de l’interface de ligne de commande (CLI) "otlp-http" pour tous les signaux. Laissez-le vide pour utiliser la valeur par défaut de la CLI, ou définissez-le sur "http/protobuf" pour exporter des données protobuf via HTTP.

Données de télémétrie de compétence et de commandes

Le runtime suit les conventions sémantiques des skills GenAI en affinant les spans existants execute_tool, sans ajouter d’opération de skill distincte. Un loader est nommé execute_tool skill {skill}. Une ressource ou un script identifié sans ambiguïté est nommé execute_tool {tool} {skill} {resource}, avec un nom de ressource relatif à la compétence. D’autres éléments de commande ajoutent le nom réel du lanceur déjà connu.

• gen_ai.skill.name et gen_ai.skill.resource.name: Disponible indépendamment de la capture de contenu
• gen_ai.skill.description et gen_ai.skill.source.uri : Requièrent la capture du contenu via TelemetryConfig
• process.executable.name: exécutable directement lancé, tel que le lanceur d’interpréteur de commandes, pas un jeton de commande deviné
• process.executable.path: chemin d’accès connu absolu ; nécessite la capture du contenu
• process.exit.code: entier, y compris zéro, lorsqu’un outil exécutant une commande signale un code de sortie ; les codes de sortie indisponibles et les échecs avant le lancement du processus sont omis

Les outils de sondage n’héritent pas des attributs de processus de la commande qu’ils lisent. Les identités exécutables en bac à sable sont omises lorsque le back-end de bac à sable ne les expose pas. Un code de sortie non nul n’implique pas que l’outil lui-même a échoué. Les définitions de compétences et les listes d’annuaires ne sont pas des ressources de compétences nommées. Les skills préchargés produisent des événements d’invocation sans span d’outil fabriqué. La préparation répétée du même contexte de compétence de l’agent sélectionné émet un reçu ; une modification du contenu ou de la provenance en émet un autre. Les sessions enfants signalent leurs propres préchargements indépendamment. Les plages de commande détachées identifient le superviseur Unix sh lancé directement ou l’exécutable Windows PowerShell sélectionné.

Les outils personnalisés qui redéfinissent les noms intégrés n’héritent pas des attributs de compétence ou de processus natifs. Les compétences visibles et activées possèdent toujours des ressources lorsque l’appel de modèle est désactivé. L’attribution de script utilise la commande post-hook et le répertoire de l’interpréteur de commandes sélectionné ; il est omis lorsque les scripts de démarrage ou les profils rendent le contexte d’exécution incertain.

Tant que les paramètres de télémétrie gérés ne sont pas définis, les mémoires tampons de suivi en attente ne capturent que les informations sur les outils indépendantes de la capture. Descriptions, URI sources et chemins exécutables observés avant que la stratégie ne soit résolue sont omis, même si la capture est activée ultérieurement. La politique finale régit le rejeu ; le suivi désactivé ou annulé efface la mémoire tampon.

Il s’agit de changements cassants de nom de télémétrie : utiliser gen_ai.skill.name au lieu de github.copilot.tool.parameters.skill_name ou github.copilot.skill.name, et utiliser gen_ai.skill.source.uri au lieu de github.copilot.skill.path. Les valeurs sources locales sont des URI de fichier, pas des chemins nus. L’événement github.copilot.skill.invoked et son contenu, la catégorie source, le déclencheur et les champs de plug-in restent Copilot spécifiques. Le contenu de compétence conserve son contrôle de capture existant.

Les attributs de compétence et les affinements d’étendue ont une stabilité de développement ; les attributs de processus ont une stabilité de candidat à la version finale.

Propagation du contexte de trace

La plupart des utilisateurs n’ont pas besoin de cela. Le TelemetryConfig ci-dessus est tout ce dont vous avez besoin pour collecter les traces depuis le CLI. La propagation du contexte de trace décrite dans cette section est une fonctionnalité avancée pour les applications qui créent leurs propres étendues OpenTelemetry et veulent qu’elles apparaissent dans la même trace distribuée que les étendues de l’interface CLI.

Le Kit de développement logiciel (SDK) peut propager le contexte de trace W3C (traceparent/tracestate) sur des charges utiles JSON-RPC afin que les étendues de votre application et les étendues de l’interface CLI soient liées dans une trace distribuée. Cela est utile lorsque, par exemple, vous souhaitez voir une étendue « gérer l’appel d’outil » dans votre application imbriquée dans l’étendue « outil d’exécution » de l’interface CLI, ou afficher l’appel du SDK en tant qu’enfant de votre étendue de gestion des demandes.

Pour l’attribution des coûts aux côtés des traces, abonnez-vous aux événements assistant.usage et examinez apiEndpoint (AssistantUsageApiEndpoint) afin de voir si un tour a utilisé Chat Completions, Responses ou Anthropic Messages ; voir Événements de session de streaming.

SDK → CLI (sortant)

Pour Node.js, fournissez une onGetTraceContext fonction de rappel dans les options du client. Cela n’est nécessaire que si votre application utilise @opentelemetry/api déjà et que vous souhaitez lier vos étendues avec les étendues de l’interface CLI. Le Kit de développement logiciel (SDK) appelle ce callback avant session.create, session.resume et 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: "..." }
  },
});

Pour Python, Go et .NET, l’injection de contexte de trace est automatique lorsque l’API OpenTelemetry/Activity respective est configurée. Aucun rappel n’est nécessaire.

CLI → SDK (entrant)

Lorsque le CLI invoque un gestionnaire d’outils, les éléments traceparent et tracestate de la portée du CLI sont disponibles dans toutes les langues :

• Go : le champ ToolInvocation.TraceContext est un(e) context.Context avec la trace déjà restaurée : utilisez-la directement comme parent pour vos étendues.
• Python : le contexte de trace est automatiquement restauré au niveau du gestionnaire via trace_context() : les étendues enfants ont automatiquement pour parent le span de la CLI.
• .NET : le contexte de trace est automatiquement restauré via RestoreTraceContext() — les instances enfants Activity sont automatiquement rattachées à l’étendue de la CLI.
• Node.js : puisque le SDK n’a aucune dépendance à OpenTelemetry, traceparent et tracestate sont transmis comme chaînes brutes dans l’objet ToolInvocation. Restaurez le contexte manuellement si nécessaire :

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

Dépendances par langage

References

• Conventions sémantiques OpenTelemetry GenAI
• Conventions sémantiques MCP OpenTelemetry
• Kit de développement logiciel (SDK) OpenTelemetry Python
• Documentation du SDK Copilot