Passer au contenu principal

​
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.

​
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

OptionDescription
otlpEndpointURL de l’endpoint OTLP HTTP
filePathChemin de fichier pour la sortie de traces en JSON-lines
exporterType"otlp-http" ou "file"
sourceNameNom du scope d’instrumentation
captureContentCapturer 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

PaquetRôle
open-telemetry/apiPropagation automatique du Trace Context (suggest, optionnel)
open-telemetry/sdkExport 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.
Dernière modification le 13 juillet 2026

Sujets connexes

Démarrer - GitHub Copilot SDK pour LaravelClasse LotteryIntroduction à Laravel NightwatchLaravel Telescope