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

> Laravel Copilot SDK で OpenTelemetry を有効化し、アプリと Copilot CLI の Trace Context を連携する方法を説明します。

## OpenTelemetry

Copilot CLI には OpenTelemetry によるトレース機能が組み込まれています。SDK 側で設定するだけで、CLI プロセスのトレースデータを収集できます。

## 基本的な使い方

### CLIプロセスのトレース有効化

`config/copilot.php` に telemetry 設定を追加するか、直接オプションで指定します。

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

または直接指定します。

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

クライアントを直接使う場合:

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

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

### TelemetryConfigオプション

| オプション            | 説明                            |
| ---------------- | ----------------------------- |
| `otlpEndpoint`   | OTLP HTTPエンドポイントURL           |
| `filePath`       | JSON-linesトレース出力のファイルパス       |
| `exporterType`   | `"otlp-http"` または `"file"`    |
| `sourceName`     | インストルメンテーションスコープ名             |
| `captureContent` | メッセージ内容（プロンプト、レスポンス）をキャプチャするか |

## W3C Trace Context プロパゲーション

<Info>
  ほとんどのユーザーにはこの機能は不要です。上記の `TelemetryConfig` だけで CLI のトレースを収集できます。以下はアプリケーション側で独自の OpenTelemetry スパンを作成し、CLI のスパンと同じ分散トレースに表示させたい場合の高度な機能です。
</Info>

SDK は `session.create`、`session.resume`、`session.send` の JSON-RPC リクエストに W3C Trace Context（`traceparent`/`tracestate`）を自動的に注入します。

### 自動プロパゲーション（推奨）

`open-telemetry/api` パッケージをインストールするだけで、トレースコンテキストが自動的に伝搬されます。

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

インストール後は特別な設定不要で、アプリケーションのスパンと CLI のスパンが同一の分散トレースにリンクされます。

### カスタムプロバイダー

独自のトレースコンテキスト取得ロジックを使いたい場合:

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

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

### SDK → CLI（アウトバウンド）

以下の RPC 呼び出しに自動的に `traceparent`/`tracestate` が注入されます。

* `session.create` — セッション作成時
* `session.resume` — セッション再開時
* `session.send` — メッセージ送信時

### CLI → SDK（インバウンド）

CLI がツールを呼び出す際、ツールハンドラの `$invocation` 配列にトレースコンテキストが含まれます。

```php theme={null}
$session->registerTools([
    [
        'name' => 'my-tool',
        'description' => 'My custom tool',
        'handler' => function (array $args, array $invocation) {
            // CLIのスパンからのトレースコンテキスト
            $traceparent = $invocation['traceparent'] ?? null;
            $tracestate = $invocation['tracestate'] ?? null;

            // open-telemetry/apiがインストールされていれば
            // コンテキストは自動的に復元され、
            // ここで作成するスパンはCLIのスパンの子になります

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

`open-telemetry/api` がインストールされている場合、ツールハンドラ実行中の OpenTelemetry コンテキストは CLI のスパンに自動的にリンクされます。明示的に `traceparent` を使う必要はありません。

## 依存関係

| パッケージ                | 用途                                 |
| -------------------- | ---------------------------------- |
| `open-telemetry/api` | 自動 Trace Context 伝搬（suggest、オプション） |
| `open-telemetry/sdk` | トレースデータのエクスポート                     |

`open-telemetry/api` は `composer.json` の `suggest` に含まれています。インストールされていなくても、SDK 自体は正常に動作します。

<Info>
  最新情報は [GitHub リポジトリ](https://github.com/invokable/laravel-copilot-sdk) を参照してください。
</Info>