メインコンテンツへスキップ

Documentation Index

Fetch the complete documentation index at: https://kawax.biz/llms.txt

Use this file to discover all available pages before exploring further.

OpenTelemetry

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

基本的な使い方

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

config/copilot.php に telemetry 設定を追加するか、直接オプションで指定します。
// config/copilot.php
'telemetry' => [
    'otlpEndpoint' => 'http://localhost:4318',
],
または直接指定します。
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\TelemetryConfig;

Copilot::useStdio([
    'telemetry' => new TelemetryConfig(
        otlpEndpoint: 'http://localhost:4318',
    )
]);

$response = Copilot::run(prompt: 'Hello');
クライアントを直接使う場合:
use Revolution\Copilot\Client;
use Revolution\Copilot\Types\TelemetryConfig;

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

TelemetryConfigオプション

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

W3C Trace Context プロパゲーション

ほとんどのユーザーにはこの機能は不要です。上記の TelemetryConfig だけで CLI のトレースを収集できます。以下はアプリケーション側で独自の OpenTelemetry スパンを作成し、CLI のスパンと同じ分散トレースに表示させたい場合の高度な機能です。
SDK は session.createsession.resumesession.send の JSON-RPC リクエストに W3C Trace Context(traceparent/tracestate)を自動的に注入します。

自動プロパゲーション(推奨)

open-telemetry/api パッケージをインストールするだけで、トレースコンテキストが自動的に伝搬されます。
composer require open-telemetry/api open-telemetry/sdk
インストール後は特別な設定不要で、アプリケーションのスパンと CLI のスパンが同一の分散トレースにリンクされます。

カスタムプロバイダー

独自のトレースコンテキスト取得ロジックを使いたい場合:
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 配列にトレースコンテキストが含まれます。
$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/apicomposer.jsonsuggest に含まれています。インストールされていなくても、SDK 自体は正常に動作します。
最新情報は GitHub リポジトリ を参照してください。
Last modified on April 22, 2026