OtelExporter

將 Trace 及日誌傳送至任何兼容 OpenTelemetry 的可觀測性平台。Trace 採用標準化的 GenAI semantic convention；日誌會保留原有的嚴重程度及訊息內容，並透過 OTEL log record 的原生 trace context，以及 mastra.traceId / mastra.spanId 屬性與 Trace 建立關聯。

建構函式

new OtelExporter(config: OtelExporterConfig)

OtelExporterConfig

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

Provider 設定

Dash0Config

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

SignozConfig

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

NewRelicConfig

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

TraceloopConfig

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

LaminarConfig

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

CustomConfig

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

方法

exportTracingEvent

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

將 tracing 事件匯出至已設定的 OTEL backend。

flush

async flush(): Promise<void>

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

shutdown

async shutdown(): Promise<void>

寫入待處理的 Trace，並關閉 exporter。

用法範例

零設定（使用環境變數）

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

明確設定

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

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

使用自訂 endpoint

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 屬性。

用法

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

Tag 的儲存方式

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

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

備註

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

相關內容

• OtelExporter 指南：包含 Provider 設定的設定指南
• OtelBridge：用於雙向整合 OTEL context
• Tracing 概覽：一般 tracing 概念