Telemetria

Descrive come abilitare OpenTelemetry in Laravel Copilot SDK e collegare il Trace Context tra applicazione e Copilot CLI.

​

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

Opzione	Descrizione
otlpEndpoint	URL dell’endpoint OTLP HTTP
filePath	Percorso file di output dei trace JSON-lines
exporterType	"otlp-http" o "file"
sourceName	Nome dello scope di instrumentation
captureContent	Se 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

Pacchetto	Uso
open-telemetry/api	Propagazione automatica del Trace Context (suggest, opzionale)
open-telemetry/sdk	Esportazione 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.