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

# Telemetria

> Descrive come abilitare OpenTelemetry in Laravel Copilot SDK e collegare il Trace Context tra applicazione e Copilot CLI.

## OpenTelemetry

Copilot CLI include il tracciamento OpenTelemetry integrato. Con la sola configurazione lato SDK puoi raccogliere i dati di trace del processo CLI.

## Uso di base

### Abilitare il tracing del processo CLI

Aggiungi la configurazione telemetry in `config/copilot.php` o passala direttamente come opzione.

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

Oppure specificala direttamente.

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

Uso diretto del client:

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

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

### Opzioni di TelemetryConfig

| Opzione          | Descrizione                                               |
| ---------------- | --------------------------------------------------------- |
| `otlpEndpoint`   | URL dell'endpoint OTLP HTTP                               |
| `filePath`       | Percorso file di output dei trace JSON-lines              |
| `exporterType`   | `"otlp-http"` o `"file"`                                  |
| `sourceName`     | Nome dello scope di instrumentation                       |
| `captureContent` | Se catturare il contenuto dei messaggi (prompt, risposte) |

## Propagazione del W3C Trace Context

<Info>
  Per la maggior parte degli utenti questa funzionalità non è necessaria. Con la sola `TelemetryConfig` sopra puoi raccogliere i trace della CLI. Quanto segue è una funzionalità avanzata utile se vuoi creare span OpenTelemetry propri dall'applicazione e farli comparire nello stesso trace distribuito degli span della CLI.
</Info>

L'SDK inietta automaticamente il W3C Trace Context (`traceparent`/`tracestate`) nelle richieste JSON-RPC `session.create`, `session.resume` e `session.send`.

### Propagazione automatica (consigliata)

Basta installare il pacchetto `open-telemetry/api` per far propagare automaticamente il trace context.

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

Dopo l'installazione, senza configurazioni particolari, gli span dell'applicazione e quelli della CLI sono collegati nello stesso trace distribuito.

### Provider personalizzato

Se vuoi usare una logica personalizzata per ottenere il 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 (in uscita)

`traceparent`/`tracestate` vengono automaticamente iniettati nelle seguenti chiamate RPC.

* `session.create` — alla creazione della sessione
* `session.resume` — alla ripresa della sessione
* `session.send` — all'invio del messaggio

### CLI → SDK (in entrata)

Quando la CLI invoca uno strumento, l'array `$invocation` dell'handler dello strumento contiene il trace context.

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

            // Se open-telemetry/api è installato,
            // il contesto viene ripristinato automaticamente e
            // gli span creati qui diventano figli dello span della CLI

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

Se `open-telemetry/api` è installato, il contesto OpenTelemetry durante l'esecuzione dell'handler dello strumento è collegato automaticamente allo span della CLI. Non serve usare esplicitamente `traceparent`.

## Dipendenze

| Pacchetto            | Uso                                                            |
| -------------------- | -------------------------------------------------------------- |
| `open-telemetry/api` | Propagazione automatica del Trace Context (suggest, opzionale) |
| `open-telemetry/sdk` | Esportazione dei dati di trace                                 |

`open-telemetry/api` è incluso nel `suggest` di `composer.json`. Anche se non è installato, l'SDK funziona correttamente.

<Info>
  Per le informazioni più recenti fai riferimento al [repository GitHub](https://github.com/invokable/laravel-copilot-sdk).
</Info>


## Related topics

- [Introduzione - GitHub Copilot SDK for Laravel](/it/packages/laravel-copilot-sdk/getting-started.md)
- [Introduzione a Laravel Nightwatch](/it/blog/nightwatch-introduction.md)
- [Laravel Telescope](/it/telescope.md)