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

# Telemetry

> Leer hoe je OpenTelemetry inschakelt in de Laravel Copilot SDK en de Trace Context van je app koppelt aan de Copilot CLI.

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

## Basisgebruik

### Tracing van het CLI-proces inschakelen

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

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

Of geef het rechtstreeks op.

```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');
```

Als je de client rechtstreeks gebruikt:

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

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

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.

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

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

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

<Info>
  Zie de [GitHub-repository](https://github.com/invokable/laravel-copilot-sdk) voor de meest recente informatie.
</Info>


## Related topics

- [Streaming events](/nl/packages/laravel-copilot-sdk/streaming-events.md)