Télémétrie

Activez OpenTelemetry avec Laravel Copilot SDK et propagez le Trace Context entre votre application et le Copilot CLI.

​

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

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.