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

# Télémétrie

> Activez OpenTelemetry avec Laravel Copilot SDK et propagez le Trace Context entre votre application et le Copilot CLI.

## OpenTelemetry

Le Copilot CLI intègre un tracing OpenTelemetry. Il suffit de le configurer côté SDK pour collecter les données de trace du processus CLI.

## Utilisation de base

### Activer le tracing du processus CLI

Ajoutez la configuration telemetry à `config/copilot.php` ou spécifiez-la directement en option.

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

Ou directement :

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

Avec le client directement :

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

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

### Options de TelemetryConfig

| Option           | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `otlpEndpoint`   | URL de l'endpoint OTLP HTTP                              |
| `filePath`       | Chemin de fichier pour la sortie de traces en JSON-lines |
| `exporterType`   | `"otlp-http"` ou `"file"`                                |
| `sourceName`     | Nom du scope d'instrumentation                           |
| `captureContent` | Capturer le contenu des messages (prompts, réponses)     |

## Propagation du W3C Trace Context

<Info>
  La plupart des utilisateurs n'ont pas besoin de cette fonctionnalité. La `TelemetryConfig` ci-dessus suffit à collecter les traces du CLI. Ci-dessous, il s'agit d'une capacité avancée pour ceux qui créent leurs propres spans OpenTelemetry côté application et souhaitent les voir dans la même trace distribuée que celles du CLI.
</Info>

Le SDK injecte automatiquement le W3C Trace Context (`traceparent`/`tracestate`) dans les requêtes JSON-RPC `session.create`, `session.resume` et `session.send`.

### Propagation automatique (recommandée)

Il suffit d'installer le paquet `open-telemetry/api` pour que le trace context soit propagé automatiquement.

```shell theme={null}
composer require open-telemetry/api open-telemetry/sdk
```

Une fois installé, aucune configuration supplémentaire n'est nécessaire : les spans de votre application et ceux du CLI sont liés dans la même trace distribuée.

### Fournisseur personnalisé

Pour utiliser votre propre logique de récupération du trace context :

```php theme={null}
use Revolution\Copilot\Support\TraceContext;

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

### SDK → CLI (sortant)

`traceparent`/`tracestate` sont injectés automatiquement dans les appels RPC suivants.

* `session.create` — création de session
* `session.resume` — reprise de session
* `session.send` — envoi de message

### CLI → SDK (entrant)

Lorsque le CLI appelle un outil, le trace context se retrouve dans le tableau `$invocation` du gestionnaire d'outil.

```php theme={null}
$session->registerTools([
    [
        'name' => 'my-tool',
        'description' => 'My custom tool',
        'handler' => function (array $args, array $invocation) {
            // Trace context provenant du span du CLI
            $traceparent = $invocation['traceparent'] ?? null;
            $tracestate = $invocation['tracestate'] ?? null;

            // Si open-telemetry/api est installé,
            // le contexte est restauré automatiquement
            // et les spans créés ici deviennent enfants du span CLI

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

Si `open-telemetry/api` est installé, le contexte OpenTelemetry pendant l'exécution du gestionnaire d'outil est automatiquement lié au span du CLI. Il n'est pas nécessaire d'utiliser explicitement `traceparent`.

## Dépendances

| Paquet               | Rôle                                                            |
| -------------------- | --------------------------------------------------------------- |
| `open-telemetry/api` | Propagation automatique du Trace Context (`suggest`, optionnel) |
| `open-telemetry/sdk` | Export des données de trace                                     |

`open-telemetry/api` est référencé en `suggest` de `composer.json`. Le SDK fonctionne aussi sans qu'il soit installé.

<Info>
  Pour les dernières informations, consultez le [dépôt GitHub](https://github.com/invokable/laravel-copilot-sdk).
</Info>


## Related topics

- [Démarrer - GitHub Copilot SDK pour Laravel](/fr/packages/laravel-copilot-sdk/getting-started.md)
- [Classe Lottery](/fr/advanced/lottery.md)
- [Introduction à Laravel Nightwatch](/fr/blog/nightwatch-introduction.md)
- [Laravel Telescope](/fr/telescope.md)