Skip to main content

OpenTelemetry

The Copilot CLI has built-in OpenTelemetry tracing. Just configure it from the SDK side to collect trace data from the CLI process.

Basic usage

Enabling CLI process tracing

Add telemetry settings to config/copilot.php, or pass them directly as an option.
Or specify them directly.
Using the client directly:

TelemetryConfig options

W3C Trace Context propagation

Most users don’t need this feature. The TelemetryConfig above is enough to collect CLI traces. What follows is an advanced feature for cases where you want to create your own OpenTelemetry spans in the application and see them together with the CLI’s spans in the same distributed trace.
The SDK automatically injects W3C Trace Context (traceparent / tracestate) into the session.create, session.resume, and session.send JSON-RPC requests. Just install the open-telemetry/api package and the trace context propagates automatically.
After installation, no special configuration is required — the application’s spans and the CLI’s spans are linked in the same distributed trace.

Custom provider

To use your own trace-context lookup logic:

SDK → CLI (outbound)

traceparent / tracestate are automatically injected into the following RPC calls.
  • session.create — on session creation
  • session.resume — on session resume
  • session.send — on message send

CLI → SDK (inbound)

When the CLI invokes a tool, the trace context is included in the tool handler’s $invocation array.
If open-telemetry/api is installed, the OpenTelemetry context inside the tool handler is automatically linked to the CLI’s span. You don’t need to use traceparent explicitly.

Dependencies

open-telemetry/api is included in composer.json’s suggest. The SDK works fine without it installed.
For the latest updates, see the GitHub repository.
Last modified on August 2, 2026