Vai al contenuto principale

​
OpenTelemetry

Copilot CLI include il tracciamento OpenTelemetry integrato. Con la sola configurazione lato SDK puoi raccogliere i dati di trace del processo CLI.

​
Uso di base

​
Abilitare il tracing del processo CLI

Aggiungi la configurazione telemetry in config/copilot.php o passala direttamente come opzione. 
// config/copilot.php
'telemetry' => [
    'otlpEndpoint' => 'http://localhost:4318',
],
Oppure specificala direttamente. 
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\TelemetryConfig;

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

$response = Copilot::run(prompt: 'Hello');
Uso diretto del client: 
use Revolution\Copilot\Client;
use Revolution\Copilot\Types\TelemetryConfig;

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

​
Opzioni di TelemetryConfig

OpzioneDescrizione
otlpEndpointURL dell’endpoint OTLP HTTP
filePathPercorso file di output dei trace JSON-lines
exporterType"otlp-http" o "file"
sourceNameNome dello scope di instrumentation
captureContentSe catturare il contenuto dei messaggi (prompt, risposte)

​
Propagazione del W3C Trace Context

Per la maggior parte degli utenti questa funzionalità non è necessaria. Con la sola TelemetryConfig sopra puoi raccogliere i trace della CLI. Quanto segue è una funzionalità avanzata utile se vuoi creare span OpenTelemetry propri dall’applicazione e farli comparire nello stesso trace distribuito degli span della CLI.
L’SDK inietta automaticamente il W3C Trace Context (traceparent/tracestate) nelle richieste JSON-RPC session.create, session.resume e session.send.

​
Propagazione automatica (consigliata)

Basta installare il pacchetto open-telemetry/api per far propagare automaticamente il trace context. 
composer require open-telemetry/api open-telemetry/sdk
Dopo l’installazione, senza configurazioni particolari, gli span dell’applicazione e quelli della CLI sono collegati nello stesso trace distribuito.

​
Provider personalizzato

Se vuoi usare una logica personalizzata per ottenere il trace context: 
use Revolution\Copilot\Support\TraceContext;

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

​
SDK → CLI (in uscita)

traceparent/tracestate vengono automaticamente iniettati nelle seguenti chiamate RPC.
  • session.create — alla creazione della sessione
  • session.resume — alla ripresa della sessione
  • session.send — all’invio del messaggio

​
CLI → SDK (in entrata)

Quando la CLI invoca uno strumento, l’array $invocation dell’handler dello strumento contiene il trace context. 
$session->registerTools([
    [
        'name' => 'my-tool',
        'description' => 'My custom tool',
        'handler' => function (array $args, array $invocation) {
            // Trace context dallo span della CLI
            $traceparent = $invocation['traceparent'] ?? null;
            $tracestate = $invocation['tracestate'] ?? null;

            // Se open-telemetry/api è installato,
            // il contesto viene ripristinato automaticamente e
            // gli span creati qui diventano figli dello span della CLI

            return 'result';
        },
    ],
]);
Se open-telemetry/api è installato, il contesto OpenTelemetry durante l’esecuzione dell’handler dello strumento è collegato automaticamente allo span della CLI. Non serve usare esplicitamente traceparent.

​
Dipendenze

PacchettoUso
open-telemetry/apiPropagazione automatica del Trace Context (suggest, opzionale)
open-telemetry/sdkEsportazione dei dati di trace
open-telemetry/api è incluso nel suggest di composer.json. Anche se non è installato, l’SDK funziona correttamente.
Per le informazioni più recenti fai riferimento al repository GitHub.
Ultima modifica il 13 luglio 2026

Argomenti correlati

Introduzione - GitHub Copilot SDK for LaravelIntroduzione a Laravel NightwatchLaravel Telescope