Zum Hauptinhalt springen

OpenTelemetry

In die Copilot CLI ist eine Tracing-Funktion auf Basis von OpenTelemetry integriert. Allein durch die Konfiguration auf SDK-Seite können Sie Trace-Daten des CLI-Prozesses sammeln.

Grundlegende Verwendung

Tracing für den CLI-Prozess aktivieren

Ergänzen Sie die Telemetry-Konfiguration in config/copilot.php oder geben Sie sie direkt als Option an.
// config/copilot.php
'telemetry' => [
    'otlpEndpoint' => 'http://localhost:4318',
],
Oder direkt angeben.
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\TelemetryConfig;

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

$response = Copilot::run(prompt: 'Hello');
Bei direkter Verwendung des Clients:
use Revolution\Copilot\Client;
use Revolution\Copilot\Types\TelemetryConfig;

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

Optionen von TelemetryConfig

OptionBeschreibung
otlpEndpointURL des OTLP-HTTP-Endpunkts
filePathDateipfad für die JSON-lines-Trace-Ausgabe
exporterType"otlp-http" oder "file"
sourceNameName des Instrumentierungs-Scopes
captureContentOb Nachrichteninhalte (Prompts, Antworten) erfasst werden

W3C-Trace-Context-Propagation

Für die meisten Nutzer ist diese Funktion nicht erforderlich. Bereits mit der obigen TelemetryConfig werden CLI-Traces gesammelt. Das Folgende ist eine erweiterte Funktion, wenn Sie auf Anwendungsseite eigene OpenTelemetry-Spans erzeugen und im selben Distributed Trace wie die CLI-Spans anzeigen möchten.
Das SDK injiziert bei den JSON-RPC-Requests session.create, session.resume und session.send automatisch den W3C-Trace-Context (traceparent/tracestate).

Automatische Propagation (empfohlen)

Sie installieren lediglich das Paket open-telemetry/api, dann wird der Trace-Kontext automatisch weitergegeben.
composer require open-telemetry/api open-telemetry/sdk
Nach der Installation werden Anwendungs- und CLI-Spans ohne Zusatzkonfiguration im selben Distributed Trace verknüpft.

Benutzerdefinierter Provider

Wenn Sie eine eigene Logik zur Ermittlung des Trace-Kontexts verwenden möchten:
use Revolution\Copilot\Support\TraceContext;

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

SDK → CLI (Outbound)

traceparent/tracestate werden automatisch in folgende RPC-Aufrufe injiziert.
  • session.create — Beim Erstellen einer Session
  • session.resume — Beim Fortsetzen einer Session
  • session.send — Beim Senden einer Nachricht

CLI → SDK (Inbound)

Wenn die CLI ein Tool aufruft, ist im Array $invocation des Tool-Handlers der Trace-Kontext enthalten.
$session->registerTools([
    [
        'name' => 'my-tool',
        'description' => 'My custom tool',
        'handler' => function (array $args, array $invocation) {
            // Trace-Kontext aus dem CLI-Span
            $traceparent = $invocation['traceparent'] ?? null;
            $tracestate = $invocation['tracestate'] ?? null;

            // Wenn open-telemetry/api installiert ist,
            // wird der Kontext automatisch wiederhergestellt und
            // hier erzeugte Spans werden zu Kindern des CLI-Spans.

            return 'result';
        },
    ],
]);
Ist open-telemetry/api installiert, wird der OpenTelemetry-Kontext während der Tool-Handler-Ausführung automatisch mit dem CLI-Span verknüpft. Ein expliziter Umgang mit traceparent ist nicht nötig.

Abhängigkeiten

PaketZweck
open-telemetry/apiAutomatische Trace-Kontext-Weitergabe (suggest, optional)
open-telemetry/sdkExport der Trace-Daten
open-telemetry/api ist im suggest-Bereich der composer.json gelistet. Auch ohne diese Installation funktioniert das SDK selbst einwandfrei.
Aktuelle Informationen finden Sie im GitHub-Repository.
Zuletzt geändert am 13. Juli 2026