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.

// config/copilot.php
'telemetry' => [
    'otlpEndpoint' => 'http://localhost:4318',
],

O indícalo directamente:

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:

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

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.

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.

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:

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.

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

Consulta la información más reciente en el repositorio de GitHub.