Telemetry

OpenTelemetry

De Copilot CLI heeft ingebouwde tracing via OpenTelemetry. Je hoeft dit alleen aan de SDK-kant te configureren om tracedata van het CLI-proces te verzamelen.

Telemetrie van modelaanroepen

Via het CLI-event assistant.usage kun je aantallen opvragen over toolaanroepen van vóór het opschonen van de request.

use Revolution\Copilot\Enums\SessionEventType;

if ($event->type === SessionEventType::ASSISTANT_USAGE) {
    $customCalls = $event->customToolCallCount();
    $orphanCalls = $event->orphanToolCallCount();
    $unmatchedResults = $event->unmatchedToolResultCount();
}

data['requestFingerprint'] van het event model.call_failure kan structurele informatie over de mislukte request bevatten, zoals het aantal berichten, afbeeldingen en toolaanroepen. De inhoud van de request wordt niet opgenomen. errorCode en errorType zijn waarden afkomstig van de server en bedoeld voor beperkte telemetrie. De SDK bewaart de eventdata ongewijzigd. Stuur deze waarden en errorMessage niet door naar niet-goedgekeurde logs of externe diensten.

GitHub-telemetry-events ontvangen

Los van OpenTelemetry kun je GitHub-telemetry-events ontvangen met de clientoptie onGitHubTelemetry (of on_github_telemetry). Wanneer je een handler instelt, schakelt de SDK het doorsturen in bij het verbinden en telkens wanneer een sessie wordt aangemaakt of hervat. De clienthandler heeft voorrang op enableGitHubTelemetryForwarding: false in de sessieconfiguratie.

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

Basisgebruik

Tracing van het CLI-proces inschakelen

Voeg een telemetry-configuratie toe aan config/copilot.php, of geef die rechtstreeks als optie mee.

// config/copilot.php
'telemetry' => [
    'otlpEndpoint' => 'http://localhost:4318',
],

Of geef het rechtstreeks op.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\TelemetryConfig;

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

$response = Copilot::run(prompt: 'Hello');

Als je de client rechtstreeks gebruikt:

use Revolution\Copilot\Client;
use Revolution\Copilot\Types\TelemetryConfig;

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

TelemetryConfig-opties

Optie	Beschrijving
`otlpEndpoint`	OTLP HTTP-endpoint-URL
`filePath`	Bestandspad voor JSON-lines trace-uitvoer
`exporterType`	`"otlp-http"` of `"file"`
`sourceName`	Naam van de instrumentatiescope
`captureContent`	Of berichtinhoud (prompts, responses) moet worden vastgelegd

W3C Trace Context-propagatie

De meeste gebruikers hebben deze functie niet nodig. Met alleen de bovenstaande TelemetryConfig kun je al traces van de CLI verzamelen. Wat volgt is een geavanceerde functie voor als je aan de applicatiekant eigen OpenTelemetry-spans wilt maken en die in dezelfde gedistribueerde trace wilt tonen als de spans van de CLI.

De SDK injecteert automatisch W3C Trace Context (traceparent/tracestate) in de JSON-RPC-requests session.create, session.resume en session.send.

Automatische propagatie (aanbevolen)

Installeer alleen het pakket open-telemetry/api en de tracecontext wordt automatisch gepropageerd.

composer require open-telemetry/api open-telemetry/sdk

Na installatie is er geen speciale configuratie nodig en worden de spans van je applicatie en de spans van de CLI gekoppeld in dezelfde gedistribueerde trace.

Custom provider

Als je je eigen logica wilt gebruiken om de tracecontext op te halen:

use Revolution\Copilot\Support\TraceContext;

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

SDK → CLI (uitgaand)

traceparent/tracestate worden automatisch geïnjecteerd in de volgende RPC-aanroepen.

session.create — bij het aanmaken van een sessie
session.resume — bij het hervatten van een sessie
session.send — bij het versturen van een bericht

CLI → SDK (inkomend)

Wanneer de CLI een tool aanroept, bevat de $invocation-array van de toolhandler de tracecontext.

$session->registerTools([
    [
        'name' => 'my-tool',
        'description' => 'My custom tool',
        'handler' => function (array $args, array $invocation) {
            // Tracecontext uit de span van de CLI
            $traceparent = $invocation['traceparent'] ?? null;
            $tracestate = $invocation['tracestate'] ?? null;

            // Als open-telemetry/api is geïnstalleerd,
            // wordt de context automatisch hersteld en
            // worden spans die je hier maakt kinderen van de CLI-span

            return 'result';
        },
    ],
]);

Als open-telemetry/api is geïnstalleerd, wordt de OpenTelemetry-context tijdens het uitvoeren van de toolhandler automatisch gekoppeld aan de span van de CLI. Je hoeft traceparent niet expliciet te gebruiken.

Afhankelijkheden

Pakket	Doel
`open-telemetry/api`	Automatische Trace Context-propagatie (suggest, optioneel)
`open-telemetry/sdk`	Exporteren van tracedata

open-telemetry/api staat in de suggest-sectie van composer.json. De SDK zelf werkt gewoon, ook als het pakket niet is geïnstalleerd.

Zie de GitHub-repository voor de meest recente informatie.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kits

Feeds en RSS

Middleware

OpenTelemetry

Telemetrie van modelaanroepen

GitHub-telemetry-events ontvangen

Basisgebruik

Tracing van het CLI-proces inschakelen

TelemetryConfig-opties

W3C Trace Context-propagatie

Automatische propagatie (aanbevolen)

Custom provider

SDK → CLI (uitgaand)

CLI → SDK (inkomend)

Afhankelijkheden

​OpenTelemetry

​Telemetrie van modelaanroepen

​GitHub-telemetry-events ontvangen

​Basisgebruik

​Tracing van het CLI-proces inschakelen

​TelemetryConfig-opties

​W3C Trace Context-propagatie

​Automatische propagatie (aanbevolen)

​Custom provider

​SDK → CLI (uitgaand)

​CLI → SDK (inkomend)

​Afhankelijkheden

OpenTelemetry

Telemetrie van modelaanroepen

GitHub-telemetry-events ontvangen

Basisgebruik

Tracing van het CLI-proces inschakelen

TelemetryConfig-opties

W3C Trace Context-propagatie

Automatische propagatie (aanbevolen)

Custom provider

SDK → CLI (uitgaand)

CLI → SDK (inkomend)

Afhankelijkheden