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

> Explica cómo habilitar OpenTelemetry en Laravel Copilot SDK y correlacionar el Trace Context entre la app y Copilot CLI.

## OpenTelemetry

Copilot CLI incluye trazas con OpenTelemetry. Con solo configurarlo en el SDK, puedes recolectar los datos de traza del proceso CLI.

## Uso básico

### Habilitar las trazas del proceso CLI

Añade la configuración `telemetry` en `config/copilot.php` o indícala directamente como opción.

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

O indícalo directamente:

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

Al usar el cliente directamente:

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

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

### Opciones de TelemetryConfig

| Opción           | Descripción                                                 |
| ---------------- | ----------------------------------------------------------- |
| `otlpEndpoint`   | URL del endpoint OTLP HTTP                                  |
| `filePath`       | Ruta del fichero para exportar trazas en formato JSON-lines |
| `exporterType`   | `"otlp-http"` o `"file"`                                    |
| `sourceName`     | Nombre del scope de instrumentación                         |
| `captureContent` | Si captura el contenido de los mensajes (prompt, respuesta) |

## Propagación de W3C Trace Context

<Info>
  La mayoría de usuarios no necesitan esta funcionalidad. Con solo `TelemetryConfig` puedes recolectar las trazas del CLI. Lo siguiente es una función avanzada para cuando quieres crear tus propios spans de OpenTelemetry en la app y verlos en la misma traza distribuida que los spans del CLI.
</Info>

El SDK inyecta automáticamente W3C Trace Context (`traceparent`/`tracestate`) en las peticiones JSON-RPC de `session.create`, `session.resume` y `session.send`.

### Propagación automática (recomendado)

Con solo instalar el paquete `open-telemetry/api`, el contexto de traza se propaga automáticamente.

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

Tras la instalación, sin configuración especial, los spans de la app y los del CLI quedan enlazados en la misma traza distribuida.

### Provider personalizado

Si quieres usar tu propia lógica de obtención de contexto de traza:

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

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

### SDK → CLI (saliente)

Se inyectan automáticamente `traceparent`/`tracestate` en las siguientes llamadas RPC:

* `session.create` — al crear la sesión
* `session.resume` — al reanudar la sesión
* `session.send` — al enviar un mensaje

### CLI → SDK (entrante)

Cuando el CLI invoca una herramienta, el contexto de traza se incluye en el array `$invocation` del handler de la herramienta.

```php theme={null}
$session->registerTools([
    [
        'name' => 'my-tool',
        'description' => 'My custom tool',
        'handler' => function (array $args, array $invocation) {
            // Contexto de traza desde el span del CLI
            $traceparent = $invocation['traceparent'] ?? null;
            $tracestate = $invocation['tracestate'] ?? null;

            // Si open-telemetry/api está instalado,
            // el contexto se restaura automáticamente,
            // y el span que crees aquí será hijo del span del CLI

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

Si `open-telemetry/api` está instalado, el contexto de OpenTelemetry durante la ejecución del handler de la herramienta se enlaza automáticamente con el span del CLI. No hace falta usar `traceparent` explícitamente.

## Dependencias

| Paquete              | Uso                                                         |
| -------------------- | ----------------------------------------------------------- |
| `open-telemetry/api` | Propagación automática de Trace Context (suggest, opcional) |
| `open-telemetry/sdk` | Exportación de los datos de traza                           |

`open-telemetry/api` figura en la sección `suggest` de `composer.json`. Aunque no esté instalado, el SDK funciona con normalidad.

<Info>
  Consulta la información más reciente en el [repositorio de GitHub](https://github.com/invokable/laravel-copilot-sdk).
</Info>


## Related topics

- [Eventos de streaming](/es/packages/laravel-copilot-sdk/streaming-events.md)