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

# OtelExporter

將 Trace 及日誌傳送至任何兼容 OpenTelemetry 的可觀測性平台。Trace 採用標準化的 GenAI semantic convention；日誌會保留原有的嚴重程度及訊息內容，並透過 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 backend。

### flush

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

在不關閉 exporter 的情況下，強制將所有緩衝中的 span 寫入 OTEL backend。這適用於無伺服器環境，讓你可確保 span 在執行環境終止前已經匯出。

### shutdown

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

寫入待處理的 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 套件。Trace 與日誌匯出功能彼此獨立：如只需要 Trace，僅安裝 Trace 套件即可；如亦要匯出日誌，請同時安裝所選 protocol 的 Trace 及日誌套件。Zipkin 不支援 OTLP 日誌。

| Protocol      | Trace 套件                                                      | 日誌套件                                                         |
| ------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
| 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`                              | 不支援                                                          |

## Tag 支援

OtelExporter 支援為 Trace 加上 tag，以便分類及篩選。Tag 只會套用至 root span，並儲存為 `mastra.tags` 屬性。

### 用法

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

### Tag 的儲存方式

為盡量兼容不同 backend，tag 會以 JSON 字串化陣列形式儲存於 `mastra.tags` span 屬性：

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

> **備註:** 雖然 OpenTelemetry 規格支援原生陣列屬性，但不少 backend（Jaeger、Zipkin、Tempo）對陣列的支援有限。JSON 字串可確保所有可觀測性平台的行為一致。

## 相關內容

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