> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetrie

> Beschreibt, wie Sie im Laravel Copilot SDK OpenTelemetry aktivieren und den Trace-Kontext zwischen Anwendung und Copilot CLI verknüpfen.

## 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.

```php theme={null}
// config/copilot.php
'telemetry' => [
    'otlpEndpoint' => 'http://localhost:4318',
],
```

Oder direkt angeben.

```php theme={null}
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:

```php theme={null}
use Revolution\Copilot\Client;
use Revolution\Copilot\Types\TelemetryConfig;

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

### Optionen von TelemetryConfig

| Option           | Beschreibung                                              |
| ---------------- | --------------------------------------------------------- |
| `otlpEndpoint`   | URL des OTLP-HTTP-Endpunkts                               |
| `filePath`       | Dateipfad für die JSON-lines-Trace-Ausgabe                |
| `exporterType`   | `"otlp-http"` oder `"file"`                               |
| `sourceName`     | Name des Instrumentierungs-Scopes                         |
| `captureContent` | Ob Nachrichteninhalte (Prompts, Antworten) erfasst werden |

## W3C-Trace-Context-Propagation

<Info>
  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.
</Info>

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.

```shell theme={null}
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:

```php theme={null}
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.

```php theme={null}
$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

| Paket                | Zweck                                                     |
| -------------------- | --------------------------------------------------------- |
| `open-telemetry/api` | Automatische Trace-Kontext-Weitergabe (suggest, optional) |
| `open-telemetry/sdk` | Export der Trace-Daten                                    |

`open-telemetry/api` ist im `suggest`-Bereich der `composer.json` gelistet. Auch ohne diese Installation funktioniert das SDK selbst einwandfrei.

<Info>
  Aktuelle Informationen finden Sie im [GitHub-Repository](https://github.com/invokable/laravel-copilot-sdk).
</Info>


## Related topics

- [Erste Schritte - GitHub Copilot SDK für Laravel](/de/packages/laravel-copilot-sdk/getting-started.md)
- [Lottery-Klasse](/de/advanced/lottery.md)