OtelExporter

将 Trace 和日志发送到任何兼容 OpenTelemetry 的可观测性平台。Trace 使用标准化的 GenAI 语义约定；日志会保留其原始严重级别和消息正文，并通过 OTEL 日志记录的原生 Trace 上下文以及 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 后端。

flush

async flush(): Promise<void>

强制将缓冲区中的所有 Span 刷新到 OTEL 后端，而不关闭 Exporter。适用于需要确保运行时终止前已导出 Span 的 serverless 环境。

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',
})

协议要求

不同 Provider 需要不同的 OTEL Exporter 包。Trace 和日志导出彼此独立：如果只需要 Trace，请仅安装 Trace 包；如果还需要导出日志，请同时安装所选协议对应的 Trace 包和日志包。Zipkin 不支持 OTLP 日志。

协议	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	不支持

标签支持

OtelExporter 支持使用 Trace 标签进行分类和筛选。标签仅应用于根 Span，并存储为 mastra.tags 属性。

用法

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

标签的存储方式

标签以 JSON 字符串化数组的形式存储在 mastra.tags Span 属性中，以最大程度兼容后端：

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

备注

尽管 OpenTelemetry 规范支持原生数组属性，但许多后端（Jaeger、Zipkin、Tempo）对数组的支持有限。JSON 字符串可确保在所有可观测性平台上保持一致的行为。

相关内容

• OtelExporter 指南：包含 Provider 配置的设置指南
• OtelBridge：用于双向 OTEL 上下文集成
• Tracing 概述：常规 Tracing 概念