Télémétrie

OpenTelemetry

Le Copilot CLI intègre un tracing OpenTelemetry. Il suffit de le configurer côté SDK pour collecter les données de trace du processus CLI.

Recevoir les événements de télémétrie GitHub

Indépendamment d’OpenTelemetry, vous pouvez recevoir les événements de télémétrie GitHub avec l’option client onGitHubTelemetry (ou on_github_telemetry). Lorsque vous définissez un gestionnaire, le SDK active le transfert à la connexion ainsi qu’à chaque création ou reprise de session. Le gestionnaire du client est prioritaire sur enableGitHubTelemetryForwarding: false dans la configuration de session.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\Rpc\GitHubTelemetryNotification;

Copilot::useStdio([
    'onGitHubTelemetry' => function (GitHubTelemetryNotification $notification): void {
        if ($notification->restricted) {
            // Restricted events must only be sent to first-party Microsoft stores.
            return;
        }

        logger()->info('Copilot telemetry event', [
            'session_id' => $notification->sessionId,
            'kind' => $notification->event->kind,
        ]);
    },
]);

Utilisation de base

Activer le tracing du processus CLI

Ajoutez la configuration telemetry à config/copilot.php ou spécifiez-la directement en option.

// config/copilot.php
'telemetry' => [
    'otlpEndpoint' => 'http://localhost:4318',
],

Ou directement :

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\TelemetryConfig;

Copilot::useStdio([
    'telemetry' => new TelemetryConfig(
        otlpEndpoint: 'http://localhost:4318',
    )
]);

$response = Copilot::run(prompt: 'Hello');

Avec le client directement :

use Revolution\Copilot\Client;
use Revolution\Copilot\Types\TelemetryConfig;

$client = new Client([
    'telemetry' => new TelemetryConfig(
        otlpEndpoint: 'http://localhost:4318',
    ),
]);

Options de TelemetryConfig

Option	Description
`otlpEndpoint`	URL de l’endpoint OTLP HTTP
`filePath`	Chemin de fichier pour la sortie de traces en JSON-lines
`exporterType`	`"otlp-http"` ou `"file"`
`sourceName`	Nom du scope d’instrumentation
`captureContent`	Capturer le contenu des messages (prompts, réponses)

Propagation du W3C Trace Context

La plupart des utilisateurs n’ont pas besoin de cette fonctionnalité. La TelemetryConfig ci-dessus suffit à collecter les traces du CLI. Ci-dessous, il s’agit d’une capacité avancée pour ceux qui créent leurs propres spans OpenTelemetry côté application et souhaitent les voir dans la même trace distribuée que celles du CLI.

Le SDK injecte automatiquement le W3C Trace Context (traceparent/tracestate) dans les requêtes JSON-RPC session.create, session.resume et session.send.

Propagation automatique (recommandée)

Il suffit d’installer le paquet open-telemetry/api pour que le trace context soit propagé automatiquement.

composer require open-telemetry/api open-telemetry/sdk

Une fois installé, aucune configuration supplémentaire n’est nécessaire : les spans de votre application et ceux du CLI sont liés dans la même trace distribuée.

Fournisseur personnalisé

Pour utiliser votre propre logique de récupération du trace context :

use Revolution\Copilot\Support\TraceContext;

TraceContext::useProvider(function (): array {
    return [
        'traceparent' => '00-traceid-spanid-01',
        'tracestate' => 'vendor=value',
    ];
});

SDK → CLI (sortant)

traceparent/tracestate sont injectés automatiquement dans les appels RPC suivants.

session.create — création de session
session.resume — reprise de session
session.send — envoi de message

CLI → SDK (entrant)

Lorsque le CLI appelle un outil, le trace context se retrouve dans le tableau $invocation du gestionnaire d’outil.

$session->registerTools([
    [
        'name' => 'my-tool',
        'description' => 'My custom tool',
        'handler' => function (array $args, array $invocation) {
            // Trace context provenant du span du CLI
            $traceparent = $invocation['traceparent'] ?? null;
            $tracestate = $invocation['tracestate'] ?? null;

            // Si open-telemetry/api est installé,
            // le contexte est restauré automatiquement
            // et les spans créés ici deviennent enfants du span CLI

            return 'result';
        },
    ],
]);

Si open-telemetry/api est installé, le contexte OpenTelemetry pendant l’exécution du gestionnaire d’outil est automatiquement lié au span du CLI. Il n’est pas nécessaire d’utiliser explicitement traceparent.

Dépendances

Paquet	Rôle
`open-telemetry/api`	Propagation automatique du Trace Context (`suggest`, optionnel)
`open-telemetry/sdk`	Export des données de trace

open-telemetry/api est référencé en suggest de composer.json. Le SDK fonctionne aussi sans qu’il soit installé.

Pour les dernières informations, consultez le dépôt GitHub.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Kits de démarrage

Flux et RSS

Middleware

OpenTelemetry

Recevoir les événements de télémétrie GitHub

Utilisation de base

Activer le tracing du processus CLI

Options de TelemetryConfig

Propagation du W3C Trace Context

Propagation automatique (recommandée)

Fournisseur personnalisé

SDK → CLI (sortant)

CLI → SDK (entrant)

Dépendances

​OpenTelemetry

​Recevoir les événements de télémétrie GitHub

​Utilisation de base

​Activer le tracing du processus CLI

​Options de TelemetryConfig

​Propagation du W3C Trace Context

​Propagation automatique (recommandée)

​Fournisseur personnalisé

​SDK → CLI (sortant)

​CLI → SDK (entrant)

​Dépendances

OpenTelemetry

Recevoir les événements de télémétrie GitHub

Utilisation de base

Activer le tracing du processus CLI

Options de TelemetryConfig

Propagation du W3C Trace Context

Propagation automatique (recommandée)

Fournisseur personnalisé

SDK → CLI (sortant)

CLI → SDK (entrant)

Dépendances