Saltar al contenido principal

​
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ónDescripción
otlpEndpointURL del endpoint OTLP HTTP
filePathRuta del fichero para exportar trazas en formato JSON-lines
exporterType"otlp-http" o "file"
sourceNameNombre del scope de instrumentación
captureContentSi 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

PaqueteUso
open-telemetry/apiPropagación automática de Trace Context (suggest, opcional)
open-telemetry/sdkExportació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.
Última modificación el 13 de julio de 2026

Temas relacionados

Eventos de streaming