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

直接使用 Client 時:

```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 endpoint URL    |
| `filePath`       | JSON-lines 追蹤輸出檔案路徑       |
| `exporterType`   | `"otlp-http"` 或 `"file"`  |
| `sourceName`     | Instrumentation scope 名稱  |
| `captureContent` | 是否擷取訊息內容(prompt、response) |

## W3C Trace Context 傳遞

<Info>
  大多數使用者不需要此功能。僅使用上述 `TelemetryConfig` 即可收集 CLI 的追蹤資料。以下為進階功能,適用於在應用程式端建立自訂 OpenTelemetry span,並希望與 CLI 的 span 顯示在同一分散式追蹤中的情況。
</Info>

SDK 會自動將 W3C Trace Context(`traceparent`/`tracestate`)注入 `session.create`、`session.resume`、`session.send` 的 JSON-RPC 請求。

### 自動傳遞(建議)

只要安裝 `open-telemetry/api` 套件,追蹤 context 就會自動傳遞。

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

安裝後無需額外設定,應用程式 span 與 CLI span 就會連結至同一個分散式追蹤。

### 自訂 Provider

若要使用自訂的追蹤 context 取得邏輯:

```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 時
* `session.resume` — 恢復 Session 時
* `session.send` — 傳送訊息時

### CLI → SDK(對內)

當 CLI 呼叫工具時,工具處理器的 `$invocation` 陣列中會包含追蹤 context。

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

            // 若安裝了 open-telemetry/api,
            // context 會自動恢復,
            // 在此建立的 span 會成為 CLI span 的子 span

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

若安裝了 `open-telemetry/api`,工具處理器執行中的 OpenTelemetry context 會自動連結至 CLI 的 span。不需要明確使用 `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>


## Related topics

- [Streaming Events](/zh-TW/packages/laravel-copilot-sdk/streaming-events.md)