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

Ce guide explique comment ajouter le traçage OpenTelemetry à vos applications Copilot SDK.

<!-- markdownlint-disable GHD046 GHD005 -->

<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->

## 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 :

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="typescript" data-label="TypeScript"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">TypeScript</div>

<!-- docs-validate: skip -->

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

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

</div>

<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

<!-- docs-validate: skip -->

```python
from copilot import CopilotClient

client = CopilotClient(
    telemetry={
        "otlp_endpoint": "http://localhost:4318",
    },
)
```

</div>

<div class="ghd-codetab" data-lang="go" data-label="Go"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Go</div>

<!-- docs-validate: skip -->

```golang
client := copilot.NewClient(&copilot.ClientOptions{
    Telemetry: &copilot.TelemetryConfig{
        OTLPEndpoint: "http://localhost:4318",
    },
})
```

</div>

<div class="ghd-codetab" data-lang="dotnet" data-label=".NET"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">.NET</div>

<!-- docs-validate: skip -->

```csharp
var client = new CopilotClient(new CopilotClientOptions
{
    Telemetry = new TelemetryConfig
    {
        OtlpEndpoint = "http://localhost:4318",
    },
});
```

</div>

<div class="ghd-codetab" data-lang="java" data-label="Java"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Java</div>

<!-- docs-validate: skip -->

```java
import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;

var client = new CopilotClient(new CopilotClientOptions()
    .setTelemetry(new TelemetryConfig()
        .setOtlpEndpoint("http://localhost:4318"))
);
```

</div>

<div class="ghd-codetab" data-lang="rust" data-label="Rust"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Rust</div>

<!-- docs-validate: skip -->

```rust
use github_copilot_sdk::{Client, ClientOptions, TelemetryConfig};

let client = Client::start(ClientOptions::new()
    .with_telemetry(TelemetryConfig::new()
        .with_otlp_endpoint("http://localhost:4318"))
).await?;
```

</div>

</div>

### Options de configuration de télémétrie

| Choix                      | Node.JS          | Python            | Allez            | .NET             | Java             | Rust              | Description                                                                    |
| -------------------------- | ---------------- | ----------------- | ---------------- | ---------------- | ---------------- | ----------------- | ------------------------------------------------------------------------------ |
| Point de terminaison OTLP  | `otlpEndpoint`   | `otlp_endpoint`   | `OTLPEndpoint`   | `OtlpEndpoint`   | `otlpEndpoint`   | `otlp_endpoint`   | URL du point de terminaison HTTP OTLP                                          |
| Protocole OTLP             | `otlpProtocol`   | `otlp_protocol`   | `OTLPProtocol`   | `OtlpProtocol`   | `otlpProtocol`   | `otlp_protocol`   | Protocole HTTP OTLP pour tous les signaux : `"http/json"` ou `"http/protobuf"` |
| Chemins d'accès au fichier | `filePath`       | `file_path`       | `FilePath`       | `FilePath`       | `filePath`       | `file_path`       | Chemin du fichier pour la sortie trace au format JSON-lines                    |
| Type d’exportateur         | `exporterType`   | `exporter_type`   | `ExporterType`   | `ExporterType`   | `exporterType`   | `exporter_type`   |                                                                                |
| `"otlp-http"` ou `"file"`  |                  |                   |                  |                  |                  |                   |                                                                                |
| Nom de la source           | `sourceName`     | `source_name`     | `SourceName`     | `SourceName`     | `sourceName`     | `source_name`     | Nom de la portée d’instrumentation                                             |
| Capturer du contenu        | `captureContent` | `capture_content` | `CaptureContent` | `CaptureContent` | `captureContent` | `capture_content` | Indique s’il faut capturer le contenu du message                               |

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.

### 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](/fr/copilot/how-tos/copilot-sdk/features/streaming-events).

#### 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 :

<!-- docs-validate: skip -->

```typescript
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 :

<!-- docs-validate: skip -->

```typescript
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

| Language | Dépendance                           | Remarques                                                                                                                                                                                                                                     |
| -------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Node.JS  | —                                    | Aucune dépendance ; fournir une `onGetTraceContext` fonction de rappel pour la propagation sortante                                                                                                                                           |
| Python   | `opentelemetry-api`                  | Installer avec `pip install copilot-sdk[telemetry]`                                                                                                                                                                                           |
| Allez    | `go.opentelemetry.io/otel`           | Dépendance requise                                                                                                                                                                                                                            |
| .NET     | —                                    | Utilise le `System.Diagnostics.Activity` intégré                                                                                                                                                                                              |
| Java     | `io.opentelemetry:opentelemetry-api` | Ajoutez cette dépendance pour la configuration basée sur le Kit de développement logiciel (SDK) ; l’injection de contexte de trace est automatique lorsque l’agent openTelemetry Java ou le Kit de développement logiciel (SDK) est configuré |

## References

* [Conventions sémantiques OpenTelemetry GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
* [Conventions sémantiques MCP OpenTelemetry](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/)
* [Kit de développement logiciel (SDK) OpenTelemetry Python](https://opentelemetry.io/docs/instrumentation/python/)
* [Documentation du SDK Copilot](https://github.com/github/copilot-sdk)