OpenTelemetry exporter

OpenTelemetry（OTEL）exporter 使用标准化的 OpenTelemetry GenAI 语义约定，将 Trace 和日志发送到任何兼容 OTEL 的可观测性平台。这确保了与 Datadog、New Relic、SigNoz、MLflow、Latitude、Dash0、Traceloop、Laminar、telemetry.dev 等平台的广泛兼容性。

需要双向 OTEL 集成？

如果已有 OpenTelemetry 埋点，并希望 Mastra Trace 从活跃 OTEL span 继承上下文，请改用 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 可观测性与评估平台，可接收 OTLP Trace。请使用带 HTTP/Protobuf 的 custom Provider，指向 Latitude ingestion endpoint，并使用 API key 和项目 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 语义约定标准化为模型、Provider、token、延迟和成本字段。请使用带项目 API key 的 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 提供具备自动洞察的实时可观测性。

零配置设置
零配置设置的直接链接

设置环境变量，并使用空配置的 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',
            },
          }),
        ],
      },
    },
  }),
})

信息

从 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 监控功能的完整可观测性。

零配置设置
零配置设置的直接链接

.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 可观测性和自动 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 可观测和分析功能。

零配置设置
零配置设置的直接链接

.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、元数据和标签在 Laminar 仪表板中的呈现等 Laminar 专用功能，请考虑使用专用的 @mastra/laminar exporter。它针对 Laminar 平台提供了优化集成。

Datadog
Datadog的直接链接

Datadog APM 提供带分布式 Tracing 的应用性能监控。要通过 OTLP 将 Trace 发送到 Datadog，需要运行启用了 OTLP ingestion 的 Datadog Agent。

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。

注意

文件顶部对 @grpc/grpc-js 和 @opentelemetry/exporter-trace-otlp-grpc 的显式 import，以及 bundler.externals 配置，都是 gRPC transport 正常工作的必要条件。缺少这些设置可能会遇到连接问题。

Datadog 原生 exporter

如果需要自动 span 类型映射、LLM span 分类，以及无需 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,
      },
    },
  },
})

信号
信号的直接链接

Exporter 会发送两种 OpenTelemetry 信号：

Trace：Mastra span，通过 BatchSpanProcessor 导出。
日志：Mastra 日志事件，通过 BatchLogRecordProcessor 导出。带有 traceId 和 spanId 的日志会同时使用 OTEL 日志记录的原生 Trace 上下文和 mastra.traceId / mastra.spanId 属性与 Trace 关联，使 Datadog、Grafana 和 Honeycomb 等后端能够自动将日志与 Trace 连接。

两种信号默认启用，并共享相同的 Provider 配置。日志 endpoint 通过将 Trace endpoint 的 /v1/traces 后缀替换为 /v1/logs 派生。

要禁用某个信号，请设置 signals 选项：

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

日志导出需要安装与协议匹配的 OTLP 日志 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

如果未安装匹配的日志 exporter 软件包，日志导出会静默禁用，而 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 语义约定 v1.38.0，确保与可观测性平台兼容：

Span 命名
Span 命名的直接链接

LLM 操作：chat {model}
Tool 执行：execute_tool {tool_name}
Agent 运行：invoke_agent {agent_id}
Workflow 运行：invoke_workflow {workflow_id}

关键属性
关键属性的直接链接

gen_ai.operation.name——操作类型（chat、tool.execute 等）
gen_ai.provider.name——AI Provider（openai、anthropic 等）
gen_ai.request.model——模型标识符
gen_ai.input.messages——提供给模型的聊天历史
gen_ai.output.messages——模型返回的消息
gen_ai.usage.input_tokens——输入 token 数量
gen_ai.usage.output_tokens——输出 token 数量
gen_ai.request.temperature——采样 temperature
gen_ai.response.finish_reasons——完成原因

协议选择指南
协议选择指南的直接链接

根据 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 key 和 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 配置的直接链接

MLflowMLflow的直接链接

LatitudeLatitude的直接链接

telemetry.devtelemetry.dev的直接链接

Dash0Dash0的直接链接

零配置设置零配置设置的直接链接

显式配置显式配置的直接链接

SigNozsignoz的直接链接

零配置设置零配置设置的直接链接

显式配置显式配置的直接链接

New RelicNew Relic的直接链接

零配置设置零配置设置的直接链接

显式配置显式配置的直接链接

TraceloopTraceloop的直接链接

零配置设置零配置设置的直接链接

显式配置显式配置的直接链接

LaminarLaminar的直接链接

零配置设置零配置设置的直接链接

显式配置显式配置的直接链接

DatadogDatadog的直接链接

自定义/通用 OTEL endpoint自定义/通用 OTEL endpoint的直接链接

信号信号的直接链接

配置选项配置选项的直接链接

完整配置完整配置的直接链接

OpenTelemetry 语义约定opentelemetry-semantic-conventions的直接链接

Span 命名Span 命名的直接链接

关键属性关键属性的直接链接

协议选择指南协议选择指南的直接链接

故障排除故障排除的直接链接

缺少依赖错误缺少依赖错误的直接链接

常见问题常见问题的直接链接

相关内容相关内容的直接链接

安装
安装的直接链接

对于 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的直接链接

信号
信号的直接链接

配置选项
配置选项的直接链接

完整配置
完整配置的直接链接

`OpenTelemetry` 语义约定
opentelemetry-semantic-conventions的直接链接

Span 命名
Span 命名的直接链接

关键属性
关键属性的直接链接

协议选择指南
协议选择指南的直接链接

故障排除
故障排除的直接链接

缺少依赖错误
缺少依赖错误的直接链接

常见问题
常见问题的直接链接

相关内容
相关内容的直接链接