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

# OtelExporter

將 trace 與 log 傳送至任何與 OpenTelemetry 相容的可觀測性平台。Trace 使用標準化 GenAI semantic convention；log 保留原始 severity 與 message body，並透過 OTEL log record 的原生 trace context，以及 `mastra.traceId`／`mastra.spanId` 屬性與 trace 建立關聯。

## 建構函式

```typescript
new OtelExporter(config: OtelExporterConfig)
```

## `OtelExporterConfig`

```typescript
interface OtelExporterConfig {
  provider?: ProviderConfig
  signals?: {
    traces?: boolean
    logs?: boolean
  }
  timeout?: number
  batchSize?: number
  logLevel?: 'debug' | 'info' | 'warn' | 'error'
}
```

## Provider 設定

### `Dash0Config`

```typescript
interface Dash0Config {
  apiKey?: string
  endpoint?: string
  dataset?: string
}
```

### `SignozConfig`

```typescript
interface SignozConfig {
  apiKey?: string
  region?: 'us' | 'eu' | 'in'
  endpoint?: string
}
```

### `NewRelicConfig`

```typescript
interface NewRelicConfig {
  apiKey?: string
  endpoint?: string
}
```

### `TraceloopConfig`

```typescript
interface TraceloopConfig {
  apiKey?: string
  destinationId?: string
  endpoint?: string
}
```

### `LaminarConfig`

```typescript
interface LaminarConfig {
  apiKey?: string
  endpoint?: string
}
```

### `CustomConfig`

```typescript
interface CustomConfig {
  endpoint: string
  protocol?: 'http/json' | 'http/protobuf' | 'grpc' | 'zipkin'
  headers?: Record<string, string>
}
```

## 方法

### `exportTracingEvent`

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

將 tracing 事件匯出至設定的 OTEL 後端。

### flush

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

強制將所有緩衝的 span flush 至 OTEL 後端，而不關閉 exporter。這在 serverless 環境中特別實用，可確保 runtime 結束前已匯出 span。

### shutdown

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

Flush 待處理 trace 並關閉 exporter。

## 使用範例

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

```typescript
import { OtelExporter } from '@mastra/otel-exporter'

// Set SIGNOZ_API_KEY, SIGNOZ_REGION environment variables
const exporter = new OtelExporter({ provider: { signoz: {} } })

// Or for other providers:
// Set DASH0_API_KEY, DASH0_ENDPOINT for Dash0
// Set NEW_RELIC_LICENSE_KEY for New Relic
// Set TRACELOOP_API_KEY for Traceloop
// Set LMNR_PROJECT_API_KEY for Laminar
```

### 明確設定

```typescript
import { OtelExporter } from '@mastra/otel-exporter'

const exporter = new OtelExporter({
  provider: {
    signoz: {
      apiKey: process.env.SIGNOZ_API_KEY,
      region: 'us',
    },
  },
})
```

### 使用自訂 Endpoint

```typescript
const exporter = new OtelExporter({
  provider: {
    custom: {
      endpoint: 'https://my-collector.example.com/v1/traces',
      protocol: 'http/protobuf',
      headers: {
        'x-api-key': process.env.API_KEY,
      },
    },
  },
  timeout: 60000,
  logLevel: 'debug',
})
```

## Protocol 需求

不同 Provider 需要不同的 OTEL exporter package。Trace 與 log 匯出彼此獨立：若只需要 trace，只需安裝 trace package；若也需要匯出 log，請同時安裝所選 protocol 的 trace 與 log package。Zipkin 不支援 OTLP log。

| Protocol      | Trace package                                                 | Log package                                                  |
| ------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
| gRPC          | `@opentelemetry/exporter-trace-otlp-grpc` (+ `@grpc/grpc-js`) | `@opentelemetry/exporter-logs-otlp-grpc` (+ `@grpc/grpc-js`) |
| HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto`                    | `@opentelemetry/exporter-logs-otlp-proto`                    |
| HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`                     | `@opentelemetry/exporter-logs-otlp-http`                     |
| Zipkin        | `@opentelemetry/exporter-zipkin`                              | 不支援                                                          |

## 標籤支援

OtelExporter 支援以 trace 標籤進行分類與篩選。標籤只會套用至根 span，並儲存為 `mastra.tags` 屬性。

### 使用方式

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

### 標籤的儲存方式

為了達到最高的後端相容性，標籤會以 JSON 字串化 array 的形式儲存於 `mastra.tags` span 屬性中：

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

> **備註:** 雖然 OpenTelemetry 規格支援原生 array 屬性，但許多後端（Jaeger、Zipkin、Tempo）對 array 的支援有限。JSON 字串可確保在所有可觀測性平台上有一致的行為。

## 相關內容

- [OtelExporter 指南](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/otel)：包含 Provider 設定的建置指南
- [OtelBridge](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/bridges/otel)：用於雙向 OTEL context 整合
- [Tracing 概覽](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)：一般 tracing 概念