> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# ArthurExporter

使用 OpenTelemetry 及 OpenInference 語義慣例，將 Tracing 數據傳送至 [Arthur Engine](https://github.com/arthur-ai/arthur-engine)。

## 建構函式

```typescript
new ArthurExporter(config: ArthurExporterConfig)
```

## `ArthurExporterConfig`

```typescript
type ArthurExporterConfig = Omit<OtelExporterConfig, 'provider' | 'exporter'> & {
  apiKey?: string
  endpoint?: string
  taskId?: string
  headers?: Record<string, string>
}
```

繼承自 `OtelExporterConfig`（不包括 `provider` 及 `exporter`），當中包括：

- `timeout?: number` - 匯出逾時時間（毫秒）（預設：30000）
- `batchSize?: number` - 每批的 span 數量（預設：512）
- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - 記錄層級（預設：WARN）
- `resourceAttributes?: Record<string, any>` - 自訂資源屬性

### Metadata 傳遞

非保留的 span 屬性會序列化至 OpenInference `metadata` payload。請透過 `tracingOptions.metadata` 加入這些屬性（例如 `companyId`、`tier`）。`input`、`output`、`sessionId`、thread/user ID 及 OpenInference ID 等保留欄位會自動排除。

## 方法

### `exportTracingEvent`

```typescript
async exportTracingEvent(event: TracingEvent): Promise<void>
```

將 tracing 事件匯出至已設定的 endpoint。

### export

```typescript
async export(spans: ReadOnlySpan[]): Promise<void>
```

使用 OpenTelemetry 及 OpenInference 語義慣例批次匯出 span。

### flush

```typescript
async flush(): Promise<void>
```

在不關閉 exporter 的情況下，強制將所有已緩衝的 span 清空並匯出至已設定的 endpoint。這對 serverless 環境尤其有用，可確保 span 在 runtime 終止前完成匯出。

### shutdown

```typescript
async shutdown(): Promise<void>
```

清空待處理數據並關閉 client。

## 用法

### 零設定（使用環境變數）

```typescript
import { ArthurExporter } from '@mastra/arthur'

// Set ARTHUR_API_KEY and ARTHUR_BASE_URL (optionally ARTHUR_TASK_ID)
const exporter = new ArthurExporter()
```

### 明確設定

```typescript
import { ArthurExporter } from '@mastra/arthur'

const exporter = new ArthurExporter({
  apiKey: process.env.ARTHUR_API_KEY!,
  endpoint: 'http://localhost:3030',
  taskId: process.env.ARTHUR_TASK_ID, // Optional
})
```

## `OpenInference` 語義慣例

ArthurExporter 為生成式 AI 應用程式實作了 [OpenInference 語義慣例](https://github.com/Arize-ai/openinference/tree/main/spec)，讓不同可觀測性平台採用標準化的 trace 結構。

## Tag 支援

ArthurExporter 支援為 trace 加上 tag，以便分類和篩選。Tag 只會套用至 root span，並對應至 OpenInference 原生的 `tag.tags` 語義慣例。

### 用法

```typescript
const result = await agent.generate('Hello', {
  tracingOptions: {
    tags: ['production', 'experiment-v2', 'user-request'],
  },
})
```

### Tag 的儲存方式

Tag 使用 OpenInference `tag.tags` 屬性儲存：

```json
{
  "tag.tags": ["production", "experiment-v2", "user-request"]
}
```

## 相關內容

- [ArthurExporter 文件](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/arthur)
- [Arthur Engine 文件](https://docs.arthur.ai/)
- [Arthur Engine 儲存庫](https://github.com/arthur-ai/arthur-engine)