Telemetria

OpenTelemetry

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

Ricevere gli eventi di telemetria di GitHub

Indipendentemente da OpenTelemetry, puoi ricevere gli eventi di telemetria di GitHub con l’opzione client onGitHubTelemetry (o on_github_telemetry). Quando imposti un handler, l’SDK abilita l’inoltro alla connessione e ogni volta che una sessione viene creata o ripresa. L’handler del client ha priorità su enableGitHubTelemetryForwarding: false nella configurazione di sessione.

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,
        ]);
    },
]);

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.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kit

Feed e RSS

Middleware

OpenTelemetry

Ricevere gli eventi di telemetria di GitHub

Uso di base

Abilitare il tracing del processo CLI

Opzioni di TelemetryConfig

Propagazione del W3C Trace Context

Propagazione automatica (consigliata)

Provider personalizzato

SDK → CLI (in uscita)

CLI → SDK (in entrata)

Dipendenze

​OpenTelemetry

​Ricevere gli eventi di telemetria di GitHub

​Uso di base

​Abilitare il tracing del processo CLI

​Opzioni di TelemetryConfig

​Propagazione del W3C Trace Context

​Propagazione automatica (consigliata)

​Provider personalizzato

​SDK → CLI (in uscita)

​CLI → SDK (in entrata)

​Dipendenze

OpenTelemetry

Ricevere gli eventi di telemetria di GitHub

Uso di base

Abilitare il tracing del processo CLI

Opzioni di TelemetryConfig

Propagazione del W3C Trace Context

Propagazione automatica (consigliata)

Provider personalizzato

SDK → CLI (in uscita)

CLI → SDK (in entrata)

Dipendenze