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

# OpenTelemetry exporter

OpenTelemetry (OTEL) exporter 使用標準化的 [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)，將你的 Trace 和日誌傳送至任何兼容 OTEL 的可觀測性平台。這確保它廣泛兼容 Datadog、New Relic、SigNoz、MLflow、Latitude、Dash0、Traceloop、Laminar、telemetry.dev 等平台。

> **正在尋找雙向 OTEL 整合？:** 如果你已有 OpenTelemetry instrumentation，並希望 Mastra Trace 繼承活躍 OTEL span 的 context，請改為參閱 [OpenTelemetry Bridge](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/bridges/otel)。

## 安裝

每個 Provider 都需要特定的協議套件。請安裝基礎 exporter，以及你的 Provider 所需的協議套件：

### 適用於 HTTP/Protobuf Provider（SigNoz、New Relic、Laminar、MLflow、Latitude、telemetry.dev）

**npm**:

```bash
npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**Bun**:

```bash
bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

### 適用於 `gRPC` Provider（Dash0、Datadog）

**npm**:

```bash
npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
```

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
```

**Bun**:

```bash
bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
```

### 適用於 HTTP/JSON Provider（Traceloop）

**npm**:

```bash
npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
```

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
```

**Bun**:

```bash
bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
```

## 環境變數

所有 Provider 都支援透過環境變數進行零配置設定。設定適當的變數後，exporter 便會自動使用它們：

| Provider  | 環境變數                                                                        |
| --------- | --------------------------------------------------------------------------- |
| Dash0     | `DASH0_API_KEY`（必填）、`DASH0_ENDPOINT`（必填）、`DASH0_DATASET`（選填）                |
| SigNoz    | `SIGNOZ_API_KEY`（必填）、`SIGNOZ_REGION`（選填）、`SIGNOZ_ENDPOINT`（選填）              |
| New Relic | `NEW_RELIC_LICENSE_KEY`（必填）、`NEW_RELIC_ENDPOINT`（選填）                        |
| Traceloop | `TRACELOOP_API_KEY`（必填）、`TRACELOOP_DESTINATION_ID`、`TRACELOOP_ENDPOINT`（選填） |
| Laminar   | `LMNR_PROJECT_API_KEY`（必填）、`LAMINAR_ENDPOINT`（選填）                           |

## Provider 配置

### MLflow

[MLflow](https://mlflow.org/docs/latest/genai/tracing/integrations/listing/mastra) 透過其位於 `/v1/traces` 的 OTLP endpoint，原生支援 Mastra tracing。請配合 HTTP/Protobuf 使用 `custom` Provider，並加入 experiment header，讓 Trace 路由至正確的 MLflow experiment：

```typescript
new OtelExporter({
  provider: {
    custom: {
      endpoint: `${process.env.MLFLOW_TRACKING_URI}/v1/traces`,
      protocol: 'http/protobuf',
      headers: {
        'x-mlflow-experiment-id': process.env.MLFLOW_EXPERIMENT_ID,
      },
    },
  },
})
```

### Latitude

[Latitude](https://latitude.so) 是一個開源的 LLM 可觀測性及評估平台，可接收 OTLP Trace。請配合 HTTP/Protobuf 使用 `custom` Provider，指向 Latitude 的 ingestion endpoint，並以你的項目 API 金鑰及項目 slug 進行驗證：

```typescript
new OtelExporter({
  provider: {
    custom: {
      endpoint: 'https://ingest.latitude.so/v1/traces',
      protocol: 'http/protobuf',
      headers: {
        Authorization: `Bearer ${process.env.LATITUDE_API_KEY}`,
        'X-Latitude-Project': process.env.LATITUDE_PROJECT,
      },
    },
  },
})
```

你可在 [console.latitude.so](https://console.latitude.so/login) 註冊，亦可自行託管，並將 endpoint 指向你自己的 ingestion host。

### telemetry.dev

[telemetry.dev](https://telemetry.dev) 接收 OTLP/HTTP protobuf Trace，並將 OpenTelemetry GenAI semantic conventions 標準化為 model、Provider、token、latency 及 cost 欄位。請配合你的項目 API 金鑰使用 `custom` Provider：

```bash
TELEMETRY_DEV_API_KEY=td_live_...
```

```typescript
new OtelExporter({
  provider: {
    custom: {
      endpoint: 'https://ingest.telemetry.dev/v1/traces',
      protocol: 'http/protobuf',
      headers: {
        Authorization: `Bearer ${process.env.TELEMETRY_DEV_API_KEY}`,
      },
    },
  },
})
```

### Dash0

[Dash0](https://www.dash0.com/) 提供具備自動洞察的實時可觀測性。

#### 零配置設定

設定環境變數，並以空白配置使用 exporter：

```bash
# Required
DASH0_API_KEY=your-api-key
DASH0_ENDPOINT=ingress.us-west-2.aws.dash0.com:4317

# Optional
DASH0_DATASET=production
```

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelExporter } from '@mastra/otel-exporter'

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

#### 明確配置

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelExporter } from '@mastra/otel-exporter'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      otel: {
        serviceName: 'my-service',
        exporters: [
          new OtelExporter({
            provider: {
              dash0: {
                apiKey: process.env.DASH0_API_KEY,
                endpoint: process.env.DASH0_ENDPOINT, // e.g., 'ingress.us-west-2.aws.dash0.com:4317'
                dataset: 'production', // Optional dataset name
              },
            },
            resourceAttributes: {
              // Optional OpenTelemetry Resource Attributes for the trace
              ['deployment.environment']: 'dev',
            },
          }),
        ],
      },
    },
  }),
})
```

> **資訊:** 請從你的 dashboard 取得 Dash0 endpoint。其格式應為 `ingress.{region}.aws.dash0.com:4317`。

### `SigNoz`

[SigNoz](https://signoz.io/) 是內置 tracing 支援的開源 APM 替代方案。

#### 零配置設定

```bash
# Required
SIGNOZ_API_KEY=your-api-key

# Optional
SIGNOZ_REGION=us  # 'us' | 'eu' | 'in'
SIGNOZ_ENDPOINT=https://my-signoz.example.com  # For self-hosted
```

```typescript
new OtelExporter({ provider: { signoz: {} } })
```

#### 明確配置

```typescript
new OtelExporter({
  provider: {
    signoz: {
      apiKey: process.env.SIGNOZ_API_KEY,
      region: 'us', // 'us' | 'eu' | 'in'
      // endpoint: 'https://my-signoz.example.com', // For self-hosted
    },
  },
})
```

### New Relic

[New Relic](https://newrelic.com/) 提供具備 AI 監察功能的完整可觀測性。

#### 零配置設定

```bash
# Required
NEW_RELIC_LICENSE_KEY=your-license-key

# Optional
NEW_RELIC_ENDPOINT=https://otlp.eu01.nr-data.net  # For EU region
```

```typescript
new OtelExporter({ provider: { newrelic: {} } })
```

#### 明確配置

```typescript
new OtelExporter({
  provider: {
    newrelic: {
      apiKey: process.env.NEW_RELIC_LICENSE_KEY,
      // endpoint: 'https://otlp.eu01.nr-data.net', // For EU region
    },
  },
})
```

### Traceloop

[Traceloop](https://www.traceloop.com/) 專注於 LLM 可觀測性，並提供自動 prompt 追蹤。

#### 零配置設定

```bash
# Required
TRACELOOP_API_KEY=your-api-key

# Optional
TRACELOOP_DESTINATION_ID=my-destination
TRACELOOP_ENDPOINT=https://custom.traceloop.com
```

```typescript
new OtelExporter({ provider: { traceloop: {} } })
```

#### 明確配置

```typescript
new OtelExporter({
  provider: {
    traceloop: {
      apiKey: process.env.TRACELOOP_API_KEY,
      destinationId: 'my-destination', // Optional
    },
  },
})
```

### Laminar

[Laminar](https://laminar.sh/) 提供專門的 LLM 可觀測性及分析功能。

#### 零配置設定

```bash
# Required
LMNR_PROJECT_API_KEY=your-api-key

# Optional
LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces
```

```typescript
new OtelExporter({ provider: { laminar: {} } })
```

#### 明確配置

```typescript
new OtelExporter({
  provider: {
    laminar: {
      apiKey: process.env.LMNR_PROJECT_API_KEY,
    },
  },
})
```

> **Laminar 原生 exporter:** 如需原生 span path、metadata，以及在 Laminar dashboard 顯示 tag 等 Laminar 專屬功能，可考慮改用專用的 [`@mastra/laminar`](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/laminar) exporter。它針對 Laminar 平台提供經最佳化的整合。

### Datadog

[Datadog](https://www.datadoghq.com/) APM 提供具備 distributed tracing 的應用程式效能監察。若要透過 OTLP 將 Trace 傳送至 Datadog，你需要執行 Datadog Agent，並啟用 OTLP ingestion。

Datadog 使用 gRPC 接收 OTLP，因此需要明確 import 及進行 [bundler 配置](https://mastra.zisheng.pro/zh-HK/reference/configuration)，才能正常運作：

```typescript
// Explicitly import gRPC dependencies for the bundler
import '@grpc/grpc-js'
import '@opentelemetry/exporter-trace-otlp-grpc'
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelExporter, type ExportProtocol } from '@mastra/otel-exporter'

export const mastra = new Mastra({
  // Add grpc-js to externals so it's handled at runtime
  bundler: {
    externals: ['@grpc/grpc-js'],
  },
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-service',
        exporters: [
          new OtelExporter({
            provider: {
              custom: {
                endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317',
                protocol: (process.env.OTEL_EXPORTER_OTLP_PROTOCOL || 'grpc') as ExportProtocol,
                headers: {},
              },
            },
          }),
        ],
      },
    },
  }),
})
```

> **資訊:** 必須配置 Datadog Agent 並啟用 OTLP ingestion。請在你的 `datadog.yaml` 加入以下內容：
>
> ```yaml
> otlp_config:
>   receiver:
>     protocols:
>       grpc:
>         endpoint: 0.0.0.0:4317
> ```
>
> 在本機執行 Datadog Agent 時，預設 OTLP endpoint 為 `http://localhost:4317`。

> **注意:** 檔案頂部必須明確 import `@grpc/grpc-js` 及 `@opentelemetry/exporter-trace-otlp-grpc`，並配合 [`bundler.externals`](https://mastra.zisheng.pro/zh-HK/reference/configuration) 配置，gRPC transport 才能正常運作。缺少這些設定可能會導致連線問題。

> **Datadog 原生 exporter:** 如需自動 span type mapping、LLM span categorization，以及毋須配置 gRPC 的簡化設定等 Datadog 專屬功能，可考慮改用專用的 [`@mastra/datadog`](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/datadog) exporter。它針對 Datadog APM 平台提供經最佳化的整合。

### 自訂／通用 OTEL endpoint

如要使用其他兼容 OTEL 的平台或自訂 collector：

```typescript
new OtelExporter({
  provider: {
    custom: {
      endpoint: 'https://your-collector.example.com/v1/traces',
      protocol: 'http/protobuf', // 'http/json' | 'http/protobuf' | 'grpc'
      headers: {
        'x-api-key': process.env.API_KEY,
      },
    },
  },
})
```

## Signals

exporter 會傳送兩種 OpenTelemetry signal：

- Trace：Mastra span，透過 `BatchSpanProcessor` 匯出。
- 日誌：Mastra log event，透過 `BatchLogRecordProcessor` 匯出。帶有 `traceId` 和 `spanId` 的日誌，會同時使用 OTEL log record 的原生 trace context 及 `mastra.traceId`／`mastra.spanId` attribute，與 Trace 建立關聯，讓 Datadog、Grafana 及 Honeycomb 等 backend 可自動將日誌與 Trace 連結起來。

兩種 signal 均預設啟用，並共用相同的 Provider 配置。日誌 endpoint 會從 Trace endpoint 衍生而來，方法是將 `/v1/traces` suffix 替換為 `/v1/logs`。

如要停用某種 signal，請設定 `signals` option：

```typescript
new OtelExporter({
  provider: {/* ... */},
  signals: {
    traces: true, // default
    logs: false, // disable log export
  },
})
```

匯出日誌時，需要安裝與你所用協議相符的 OTLP log exporter 套件：

**npm**:

```bash
# HTTP/JSON
npm install @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
npm install @opentelemetry/exporter-logs-otlp-proto
# gRPC
npm install @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js
```

**pnpm**:

```bash
# HTTP/JSON
pnpm add @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
pnpm add @opentelemetry/exporter-logs-otlp-proto
# gRPC
pnpm add @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js
```

**Yarn**:

```bash
# HTTP/JSON
yarn add @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
yarn add @opentelemetry/exporter-logs-otlp-proto
# gRPC
yarn add @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js
```

**Bun**:

```bash
# HTTP/JSON
bun add @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
bun add @opentelemetry/exporter-logs-otlp-proto
# gRPC
bun add @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js
```

如果未安裝相符的 log exporter 套件，日誌匯出功能會在不顯示提示的情況下停用，而 Trace 會繼續正常運作。

## 配置選項

### 完整配置

```typescript
new OtelExporter({
  // Provider configuration (required)
  provider: {
    // Use one of: dash0, signoz, newrelic, traceloop, laminar, custom
  },

  // Per-signal toggles. Both default to true.
  signals: {
    traces: true,
    logs: true,
  },

  // Export configuration
  timeout: 30000, // Export timeout in milliseconds
  batchSize: 100, // Number of spans/logs per batch

  // Debug options
  logLevel: 'info', // 'debug' | 'info' | 'warn' | 'error'
})
```

## `OpenTelemetry` 語義慣例

exporter 遵循 [OpenTelemetry GenAI Semantic Conventions v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai)，確保兼容各種可觀測性平台：

### Span 命名

- **LLM operation**：`chat {model}`
- **Tool 執行**：`execute_tool {tool_name}`
- **Agent 運行**：`invoke_agent {agent_id}`
- **Workflow 運行**：`invoke_workflow {workflow_id}`

### 主要 attribute

- `gen_ai.operation.name` - operation type（chat、tool.execute 等）
- `gen_ai.provider.name` - AI Provider（openai、anthropic 等）
- `gen_ai.request.model` - model identifier
- `gen_ai.input.messages` - 提供予 model 的 chat history
- `gen_ai.output.messages` - model 傳回的 message
- `gen_ai.usage.input_tokens` - input token 數量
- `gen_ai.usage.output_tokens` - output token 數量
- `gen_ai.request.temperature` - sampling temperature
- `gen_ai.response.finish_reasons` - completion reason

## 協議選擇指南

請根據你的 Provider 選擇合適的協議套件：

| Provider  | 協議            | 所需套件                                       |
| --------- | ------------- | ------------------------------------------ |
| Dash0     | gRPC          | `@opentelemetry/exporter-trace-otlp-grpc`  |
| Datadog   | gRPC          | `@opentelemetry/exporter-trace-otlp-grpc`  |
| SigNoz    | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
| New Relic | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
| Traceloop | HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`  |
| Laminar   | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
| Custom    | 視乎情況          | 取決於你的 collector                            |

> **注意:** 請確保已為你的 Provider 安裝正確的協議套件。如果安裝了錯誤的套件，exporter 會提供實用的錯誤訊息。

## 疑難排解

### 缺少依賴套件錯誤

如果你看到如下錯誤：

```text
HTTP/Protobuf exporter is not installed (required for signoz).
To use HTTP/Protobuf export, install the required package:
  npm install @opentelemetry/exporter-trace-otlp-proto
```

請為你的 Provider 安裝建議的套件。

### 常見問題

1. **協議套件錯誤**：確認你已為 Provider 安裝正確的 exporter
2. **無效 endpoint**：檢查 endpoint 格式是否符合 Provider 要求
3. **驗證失敗**：確認 API 金鑰及 header 正確無誤

## 相關內容

- [Tracing 概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)
- [OpenTelemetry Bridge](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/bridges/otel)
- [OpenTelemetry GenAI Semantic Conventions v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai)
- [OTEL Exporter 參考資料](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/otel)