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

# Arthur Exporter

[Arthur](https://arthur.ai/) 透過開放原始碼的 [Arthur Engine](https://github.com/arthur-ai/arthur-engine)，為 AI 應用程式提供 Observability 與評估平台。Arthur Exporter 使用 OpenTelemetry 與 [OpenInference](https://github.com/Arize-ai/openinference/tree/main/spec) 語意慣例傳送 Trace。

## 安裝

**npm**:

```bash
npm install @mastra/arthur@latest
```

**pnpm**:

```bash
pnpm add @mastra/arthur@latest
```

**Yarn**:

```bash
yarn add @mastra/arthur@latest
```

**Bun**:

```bash
bun add @mastra/arthur@latest
```

## 設定

### 必要條件

1. **Arthur Engine instance**：按照 [Docker Compose 部署指南](https://docs.arthur.ai/docs/arthur-genai-engine-docker-compose-deployment-guide)啟動 Arthur Engine
2. **API Key**：從 `http://localhost:3030` 的 Arthur Engine UI [產生 API Key](https://docs.arthur.ai/docs/api-keys-management)
3. **Task ID**（選用）：[建立 Task](https://docs.arthur.ai/docs/create-a-task)，將 Trace 導向特定 Task

### Task 路由

Arthur Engine 會透過兩種方式將 Trace 與 Task 建立關聯：

- **依服務名稱**：在 Observability 設定中設定 `serviceName`。Arthur Engine 會自動將 Trace 導向名稱相符的 Task，並視需要建立該 Task。
- **依 Task ID**：將既有的 `taskId` 傳給 Exporter，直接把 Trace 傳送至特定 Task。

如果兩者皆有提供，則以 `taskId` 為優先。

### 環境變數

```bash
# Required
ARTHUR_API_KEY=your-api-key
ARTHUR_BASE_URL=http://localhost:3030

# Optional - route traces to a pre-existing task by ID
ARTHUR_TASK_ID=your-task-id
```

### 零設定

設定環境變數後，即可使用不帶任何設定的 Exporter：

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { ArthurExporter } from '@mastra/arthur'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      arthur: {
        serviceName: 'my-service',
        exporters: [new ArthurExporter()],
      },
    },
  }),
})
```

### 明確設定

你也可以直接傳入憑證（優先於環境變數）：

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { ArthurExporter } from '@mastra/arthur'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      arthur: {
        serviceName: 'my-service',
        exporters: [
          new ArthurExporter({
            apiKey: process.env.ARTHUR_API_KEY!,
            endpoint: process.env.ARTHUR_BASE_URL!,
            taskId: process.env.ARTHUR_TASK_ID,
          }),
        ],
      },
    },
  }),
})
```

## 設定選項

### 完整設定

```typescript
new ArthurExporter({
  // Arthur Configuration
  apiKey: 'your-api-key', // Required
  endpoint: 'http://localhost:3030', // Required
  taskId: 'your-task-id', // Optional

  // Optional OTLP settings
  headers: {
    'x-custom-header': 'value', // Additional headers for OTLP requests
  },

  // Debug and performance tuning
  logLevel: 'debug', // Logging: debug | info | warn | error
  batchSize: 512, // Batch size before exporting spans
  timeout: 30000, // Timeout in ms before exporting spans

  // Custom resource attributes
  resourceAttributes: {
    'deployment.environment': process.env.NODE_ENV,
    'service.version': process.env.APP_VERSION,
  },
})
```

### 自訂 metadata

非保留的 span attribute 會序列化至 OpenInference `metadata` payload，並顯示在 Arthur 中。你可以透過 `tracingOptions.metadata` 加入這些 attribute：

```ts
await agent.generate(input, {
  tracingOptions: {
    metadata: {
      companyId: 'acme-co',
      tier: 'enterprise',
    },
  },
})
```

系統會自動排除 `input`、`output`、`sessionId`、討論串／使用者 ID 與 OpenInference ID 等保留欄位。

## OpenInference 語意慣例

此 Exporter 實作生成式 AI 應用程式的 [OpenInference Semantic Conventions](https://github.com/Arize-ai/openinference/tree/main/spec)，在不同 Observability 平台之間提供標準化的 Trace 結構。

## 相關內容

- [Tracing 總覽](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)
- [ArthurExporter 參考](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/arthur)
- [Arthur Engine 文件](https://docs.arthur.ai/)
- [Arthur Engine repository](https://github.com/arthur-ai/arthur-engine)
- [OpenInference 規格](https://github.com/Arize-ai/openinference/tree/main/spec)