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

> Enable OpenTelemetry in the Laravel Copilot SDK and link trace contexts between your app and the Copilot CLI.

## OpenTelemetry

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

## Model call telemetry

The CLI's `assistant.usage` event exposes counts of tool calls from before request normalization.

```php theme={null}
use Revolution\Copilot\Enums\SessionEventType;

if ($event->type === SessionEventType::ASSISTANT_USAGE) {
    $customCalls = $event->customToolCallCount();
    $orphanCalls = $event->orphanToolCallCount();
    $unmatchedResults = $event->unmatchedToolResultCount();
}
```

`data['requestFingerprint']` on the `model.call_failure` event may contain structural information about the failed request, such as the number of messages, images, and tool calls. It does not include the request content. `errorCode` and `errorType` are server-provided values intended for restricted telemetry. The SDK keeps the event data as is. Don't forward these values or `errorMessage` to unapproved logs or external services.

## Receiving GitHub telemetry events

Separately from OpenTelemetry, you can receive GitHub telemetry events with the `onGitHubTelemetry` (or `on_github_telemetry`) client option. When you set a handler, the SDK enables forwarding on connect and whenever a session is created or resumed. The client handler takes precedence over `enableGitHubTelemetryForwarding: false` in the session config.

```php theme={null}
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\Rpc\GitHubTelemetryNotification;

Copilot::useStdio([
    'onGitHubTelemetry' => function (GitHubTelemetryNotification $notification): void {
        if ($notification->restricted) {
            // Restricted events must only be sent to first-party Microsoft stores.
            return;
        }

        logger()->info('Copilot telemetry event', [
            'session_id' => $notification->sessionId,
            'kind' => $notification->event->kind,
        ]);
    },
]);
```

## Basic usage

### Enabling CLI process tracing

Add telemetry settings to `config/copilot.php`, or pass them directly as an option.

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

Or specify them directly.

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

Using the client directly:

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

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

### TelemetryConfig options

| Option | Description |
| - | - |
| `otlpEndpoint` | OTLP HTTP endpoint URL |
| `filePath` | File path for JSON-lines trace output |
| `exporterType` | `"otlp-http"` or `"file"` |
| `sourceName` | Instrumentation scope name |
| `captureContent` | Whether to capture message content (prompts and responses) |

## W3C Trace Context propagation

> [!NOTE]
>
> 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.

### Automatic propagation (recommended)

Just install the `open-telemetry/api` package and the trace context propagates automatically.

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

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:

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

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

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

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

            // If open-telemetry/api is installed, the context is restored
            // automatically, and any span you create here becomes a child
            // of the CLI's span.

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

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

| Package | Purpose |
| - | - |
| `open-telemetry/api` | Automatic Trace Context propagation (suggested, optional) |
| `open-telemetry/sdk` | Exports trace data |

`open-telemetry/api` is included in `composer.json`'s `suggest`. The SDK works fine without it installed.

> [!NOTE]
>
> For the latest updates, see the [GitHub repository](https://github.com/invokable/laravel-copilot-sdk).


## Related topics

- [Getting started - GitHub Copilot SDK for Laravel](https://kawax.biz/en/packages/laravel-copilot-sdk/getting-started.md)
- [The Lottery class](https://kawax.biz/en/advanced/lottery.md)
- [Client options reference](https://kawax.biz/en/packages/laravel-copilot-sdk/client-options.md)
- [Streaming events](https://kawax.biz/en/packages/laravel-copilot-sdk/streaming-events.md)
- [Getting started with Laravel Nightwatch](https://kawax.biz/en/blog/nightwatch-introduction.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.