OpenTelemetry Exporter

OpenTelemetry (OTEL) Exporter 使用標準化的 OpenTelemetry GenAI Semantic Conventions，將你的 Trace 與 Log 傳送至任何相容 OTEL 的 Observability 平台。這確保它廣泛相容 Datadog、New Relic、SigNoz、MLflow、Latitude、Dash0、Traceloop、Laminar、telemetry.dev 等平台。

正在尋找雙向 OTEL 整合？

如果你已有 OpenTelemetry instrumentation，並希望 Mastra Trace 繼承活躍 OTEL span 的 context，請改為參閱 OpenTelemetry Bridge。

安裝
「安裝」的直接連結

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

適用於 HTTP/Protobuf Provider（SigNoz、New Relic、Laminar、MLflow、Latitude、telemetry.dev）
「適用於 HTTP/Protobuf Provider（SigNoz、New Relic、Laminar、MLflow、Latitude、telemetry.dev）」的直接連結

npm
pnpm
Yarn
Bun

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

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

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

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

適用於 `gRPC` Provider（Dash0、Datadog）
「for-grpc-providers-dash0-datadog」的直接連結

npm
pnpm
Yarn
Bun

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

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

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

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

適用於 HTTP/JSON Provider（Traceloop）
「適用於 HTTP/JSON Provider（Traceloop）」的直接連結

npm
pnpm
Yarn
Bun

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

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

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

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 設定
「Provider 設定」的直接連結

MLflow
「MLflow」的直接連結

MLflow 透過其位於 /v1/traces 的 OTLP endpoint，原生支援 Mastra tracing。請配合 HTTP/Protobuf 使用 custom Provider，並加入 experiment header，讓 Trace 路由至正確的 MLflow experiment：

src/mastra/index.ts
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」的直接連結

Latitude 是一個開放原始碼的 LLM Observability 與評估平台，可接收 OTLP Trace。請配合 HTTP/Protobuf 使用 custom Provider，指向 Latitude 的 ingestion endpoint，並以你的專案 API 金鑰及專案 slug 進行驗證：

src/mastra/index.ts
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 註冊，也可自行代管，並將 endpoint 指向你自己的 ingestion host。

telemetry.dev
「telemetry.dev」的直接連結

telemetry.dev 接收 OTLP/HTTP protobuf Trace，並將 OpenTelemetry GenAI semantic conventions 標準化為 model、Provider、token、latency 及 cost 欄位。請配合你的專案 API 金鑰使用 custom Provider：

.env
TELEMETRY_DEV_API_KEY=td_live_...

src/mastra/index.ts
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」的直接連結

Dash0 提供具備自動洞察的即時 Observability。

零設定設定
「零設定設定」的直接連結

設定環境變數，並以空白設定使用 Exporter：

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

# Optional
DASH0_DATASET=production

src/mastra/index.ts
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: {} } })],
      },
    },
  }),
})

明確設定
「明確設定」的直接連結

src/mastra/index.ts
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」的直接連結

SigNoz 是內置 tracing 支援的開源 APM 替代方案。

零設定設定
「零設定設定」的直接連結

.env
# Required
SIGNOZ_API_KEY=your-api-key

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

src/mastra/index.ts
new OtelExporter({ provider: { signoz: {} } })

明確設定
「明確設定」的直接連結

src/mastra/index.ts
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」的直接連結

New Relic 提供具備 AI 監控功能的完整 Observability。

零設定設定
「零設定設定」的直接連結

.env
# Required
NEW_RELIC_LICENSE_KEY=your-license-key

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

src/mastra/index.ts
new OtelExporter({ provider: { newrelic: {} } })

明確設定
「明確設定」的直接連結

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

Traceloop
「Traceloop」的直接連結

Traceloop 專注於 LLM Observability，並提供自動 prompt 追蹤。

零設定設定
「零設定設定」的直接連結

.env
# Required
TRACELOOP_API_KEY=your-api-key

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

src/mastra/index.ts
new OtelExporter({ provider: { traceloop: {} } })

明確設定
「明確設定」的直接連結

src/mastra/index.ts
new OtelExporter({
  provider: {
    traceloop: {
      apiKey: process.env.TRACELOOP_API_KEY,
      destinationId: 'my-destination', // Optional
    },
  },
})

Laminar
「Laminar」的直接連結

Laminar 提供專門的 LLM Observability 及分析功能。

零設定設定
「零設定設定」的直接連結

.env
# Required
LMNR_PROJECT_API_KEY=your-api-key

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

src/mastra/index.ts
new OtelExporter({ provider: { laminar: {} } })

明確設定
「明確設定」的直接連結

src/mastra/index.ts
new OtelExporter({
  provider: {
    laminar: {
      apiKey: process.env.LMNR_PROJECT_API_KEY,
    },
  },
})

Laminar 原生 Exporter

如需原生 span path、metadata，以及在 Laminar dashboard 顯示 tag 等 Laminar 專屬功能，可考慮改用專用的 @mastra/laminar Exporter。它針對 Laminar 平台提供經最佳化的整合。

Datadog
「Datadog」的直接連結

Datadog APM 提供具備 distributed Tracing 的應用程式效能監控。若要透過 OTLP 將 Trace 傳送至 Datadog，你需要執行 Datadog Agent，並啟用 OTLP ingestion。

Datadog 使用 gRPC 接收 OTLP，因此需要明確 import 及進行 bundler 設定，才能正常運作：

src/mastra/index.ts
// 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 加入以下內容：

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 設定，gRPC transport 才能正常運作。缺少這些設定可能會導致連線問題。

Datadog 原生 Exporter

如需自動 span type mapping、LLM span categorization，以及無須設定 gRPC 的簡化設定等 Datadog 專屬功能，可考慮改用專用的 @mastra/datadog Exporter。它針對 Datadog APM 平台提供經最佳化的整合。

自訂／通用 OTEL endpoint
「自訂／通用 OTEL endpoint」的直接連結

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

src/mastra/index.ts
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
「Signals」的直接連結

Exporter 會傳送兩種 OpenTelemetry signal：

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

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

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

src/mastra/index.ts
new OtelExporter({
  provider: {/* ... */},
  signals: {
    traces: true, // default
    logs: false, // disable log export
  },
})

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

npm
pnpm
Yarn
Bun

# 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

# 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

# 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

# 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 套件，Log 匯出功能會在不顯示提示的情況下停用，而 Trace 會繼續正常運作。

設定選項
「設定選項」的直接連結

完整設定
「完整設定」的直接連結

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` 語意慣例
「opentelemetry-semantic-conventions」的直接連結

Exporter 遵循 OpenTelemetry GenAI Semantic Conventions v1.38.0，確保相容各種 Observability 平台：

Span 命名
「Span 命名」的直接連結

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

主要 attribute
「主要 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 會提供實用的錯誤訊息。

疑難排解
「疑難排解」的直接連結

缺少依賴套件錯誤
「缺少依賴套件錯誤」的直接連結

如果你看到如下錯誤：

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 安裝建議的套件。

常見問題
「常見問題」的直接連結

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

安裝「安裝」的直接連結

適用於 HTTP/Protobuf Provider（SigNoz、New Relic、Laminar、MLflow、Latitude、telemetry.dev）「適用於 HTTP/Protobuf Provider（SigNoz、New Relic、Laminar、MLflow、Latitude、telemetry.dev）」的直接連結

適用於 gRPC Provider（Dash0、Datadog）「for-grpc-providers-dash0-datadog」的直接連結

適用於 HTTP/JSON Provider（Traceloop）「適用於 HTTP/JSON Provider（Traceloop）」的直接連結

環境變數「環境變數」的直接連結

Provider 設定「Provider 設定」的直接連結

MLflow「MLflow」的直接連結

Latitude「Latitude」的直接連結

telemetry.dev「telemetry.dev」的直接連結

Dash0「Dash0」的直接連結

零設定設定「零設定設定」的直接連結

明確設定「明確設定」的直接連結

SigNoz「signoz」的直接連結

零設定設定「零設定設定」的直接連結

明確設定「明確設定」的直接連結

New Relic「New Relic」的直接連結

零設定設定「零設定設定」的直接連結

明確設定「明確設定」的直接連結

Traceloop「Traceloop」的直接連結

零設定設定「零設定設定」的直接連結

明確設定「明確設定」的直接連結

Laminar「Laminar」的直接連結

零設定設定「零設定設定」的直接連結

明確設定「明確設定」的直接連結

Datadog「Datadog」的直接連結

自訂／通用 OTEL endpoint「自訂／通用 OTEL endpoint」的直接連結

Signals「Signals」的直接連結

設定選項「設定選項」的直接連結

完整設定「完整設定」的直接連結

OpenTelemetry 語意慣例「opentelemetry-semantic-conventions」的直接連結

Span 命名「Span 命名」的直接連結

主要 attribute「主要 attribute」的直接連結

協議選擇指南「協議選擇指南」的直接連結

疑難排解「疑難排解」的直接連結

缺少依賴套件錯誤「缺少依賴套件錯誤」的直接連結

常見問題「常見問題」的直接連結

相關內容「相關內容」的直接連結

安裝
「安裝」的直接連結

適用於 HTTP/Protobuf Provider（SigNoz、New Relic、Laminar、MLflow、Latitude、telemetry.dev）
「適用於 HTTP/Protobuf Provider（SigNoz、New Relic、Laminar、MLflow、Latitude、telemetry.dev）」的直接連結

適用於 `gRPC` Provider（Dash0、Datadog）
「for-grpc-providers-dash0-datadog」的直接連結

適用於 HTTP/JSON Provider（Traceloop）
「適用於 HTTP/JSON Provider（Traceloop）」的直接連結

環境變數
「環境變數」的直接連結

Provider 設定
「Provider 設定」的直接連結

MLflow
「MLflow」的直接連結

Latitude
「Latitude」的直接連結

telemetry.dev
「telemetry.dev」的直接連結

Dash0
「Dash0」的直接連結

零設定設定
「零設定設定」的直接連結

明確設定
「明確設定」的直接連結

`SigNoz`
「signoz」的直接連結

零設定設定
「零設定設定」的直接連結

明確設定
「明確設定」的直接連結

New Relic
「New Relic」的直接連結

零設定設定
「零設定設定」的直接連結

明確設定
「明確設定」的直接連結

Traceloop
「Traceloop」的直接連結

零設定設定
「零設定設定」的直接連結

明確設定
「明確設定」的直接連結

Laminar
「Laminar」的直接連結

零設定設定
「零設定設定」的直接連結

明確設定
「明確設定」的直接連結

Datadog
「Datadog」的直接連結

自訂／通用 OTEL endpoint
「自訂／通用 OTEL endpoint」的直接連結

Signals
「Signals」的直接連結

設定選項
「設定選項」的直接連結

完整設定
「完整設定」的直接連結

`OpenTelemetry` 語意慣例
「opentelemetry-semantic-conventions」的直接連結

Span 命名
「Span 命名」的直接連結

主要 attribute
「主要 attribute」的直接連結

協議選擇指南
「協議選擇指南」的直接連結

疑難排解
「疑難排解」的直接連結

缺少依賴套件錯誤
「缺少依賴套件錯誤」的直接連結

常見問題
「常見問題」的直接連結

相關內容
「相關內容」的直接連結