OpenTelemetry 导出器

🌐 OpenTelemetry Exporter

OpenTelemetry (OTEL) 导出器使用标准化的 OpenTelemetry GenAI 语义约定 将你的跟踪发送到任何兼容 OTEL 的可观测性平台。这确保了与 Datadog、New Relic、SigNoz、MLflow、Dash0、Traceloop、Laminar 等平台的广泛兼容性。

🌐 The OpenTelemetry (OTEL) exporter sends your traces to any OTEL-compatible observability platform using standardized OpenTelemetry Semantic Conventions for GenAI. This ensures broad compatibility with platforms like Datadog, New Relic, SigNoz, MLflow, Dash0, Traceloop, Laminar, and more.

在寻找双向 OTEL 集成吗？

如果你已有现有的 OpenTelemetry 仪器，并希望 Mastra 跟踪继承来自活动 OTEL 跨度的上下文，请改为参见 OpenTelemetry 桥接。

🌐 If you have existing OpenTelemetry instrumentation and want Mastra traces to inherit context from active OTEL spans, see the OpenTelemetry Bridge instead.

安装

🌐 Installation

每个提供商都需要特定的协议包。安装基础导出器以及适用于你提供商的协议包：

🌐 Each provider requires specific protocol packages. Install the base exporter plus the protocol package for your provider:

适用于 HTTP/Protobuf 提供商（SigNoz、New Relic、Laminar、MLflow）

🌐 For HTTP/Protobuf Providers (SigNoz, New Relic, Laminar, MLflow)

npm

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

pnpm

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

Yarn

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

Bun

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

用于 gRPC 提供商（Dash0、Datadog）

🌐 For gRPC Providers (Dash0, Datadog)

npm

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

pnpm

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

Yarn

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

Bun

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

针对 HTTP/JSON 提供商（Traceloop）

🌐 For HTTP/JSON Providers (Traceloop)

npm

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

pnpm

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

Yarn

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

Bun

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

环境变量

🌐 Environment Variables

所有提供商都支持通过环境变量进行零配置设置。设置相应的变量，导出器将自动使用它们：

🌐 All providers support zero-config setup via environment variables. Set the appropriate variables and the exporter will automatically use them:

提供商	环境变量
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 Configurations

MLflow

MLflow 通过其位于 /v1/traces 的 OTLP 端点支持原生 Mastra 跟踪。使用带有 HTTP/Protobuf 的 custom 提供程序，并包含实验头，以便跟踪记录到正确的 MLflow 实验中：

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

Dash0

Dash0 提供实时可观察性并具备自动洞察功能。

零配置设置

🌐 Zero-Config Setup

设置环境变量并在空配置下使用导出器：

🌐 Set environment variables and use the exporter with an empty config:

.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: {} } })],
      },
    },
  }),
});

显式配置

🌐 Explicit Configuration

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",
            },
          }),
        ],
      },
    },
  }),
});

info

从你的仪表板获取你的 Dash0 端点。它的格式应该是 ingress.{region}.aws.dash0.com:4317。

🌐 Get your Dash0 endpoint from your dashboard. It should be in the format ingress.{region}.aws.dash0.com:4317.

SigNoz

SigNoz 是一个开源的 APM 替代方案，内置追踪支持。

零配置设置

🌐 Zero-Config Setup

.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: {} } })

显式配置

🌐 Explicit Configuration

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 提供具有 AI 监控功能的全面可观测性。

零配置设置

🌐 Zero-Config Setup

.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: {} } })

显式配置

🌐 Explicit Configuration

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 专注于大型语言模型的可观测性，能够自动跟踪提示信息。

零配置设置

🌐 Zero-Config Setup

.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: {} } })

显式配置

🌐 Explicit Configuration

src/mastra/index.ts

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

Laminar

Laminar 提供专业的 LLM 可观测性和分析功能。

零配置设置

🌐 Zero-Config Setup

.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: {} } })

显式配置

🌐 Explicit Configuration

src/mastra/index.ts

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

Laminar原生导出器

对于 Laminar 特定功能，例如原生 span 路径、元数据和在 Laminar 仪表板中渲染标签，建议使用专用的 @mastra/laminar 导出器。它提供与 Laminar 平台的优化集成。

🌐 For Laminar-specific features like native span paths, metadata, and tags rendering in the Laminar dashboard, consider using the dedicated @mastra/laminar exporter instead. It provides optimized integration with Laminar's platform.

Datadog

Datadog APM 提供带有分布式跟踪的应用性能监控。要通过 OTLP 向 Datadog 发送跟踪数据，你需要运行启用了 OTLP 接收功能的 Datadog Agent。

Datadog 使用 gRPC 进行 OTLP 数据摄取，这需要明确导入并进行 打包器配置 才能正常工作：

🌐 Datadog uses gRPC for OTLP ingestion, which requires explicit imports and bundler configuration to work correctly:

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: {},
              },
            },
          }),
        ],
      },
    },
  }),
});

info

Datadog 代理必须配置为启用 OTLP 接收。将以下内容添加到你的 datadog.yaml 中：

🌐 The Datadog Agent must be configured with OTLP ingestion enabled. Add the following to your datadog.yaml:

otlp_config:
  receiver:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

在本地运行 Datadog 代理时，默认的 OTLP 端点是 http://localhost:4317。

🌐 The default OTLP endpoint is http://localhost:4317 when running the Datadog Agent locally.

warning

在文件顶部显式导入 @grpc/grpc-js 和 @opentelemetry/exporter-trace-otlp-grpc，以及 bundler.externals 配置，是 gRPC 传输正确工作所必需的。没有这些，你可能会遇到连接问题。

🌐 The explicit imports of @grpc/grpc-js and @opentelemetry/exporter-trace-otlp-grpc at the top of the file, along with the bundler.externals configuration, are required for the gRPC transport to work correctly. Without these, you may encounter connection issues.

Datadog 原生导出器

对于 Datadog 特定功能，如自动跨度类型映射、LLM 跨度分类以及无需 gRPC 配置的简化设置，建议使用专用的 @mastra/datadog 导出器。它提供与 Datadog APM 平台的优化集成。

🌐 For Datadog-specific features like automatic span type mapping, LLM span categorization, and simplified setup without gRPC configuration, consider using the dedicated @mastra/datadog exporter instead. It provides optimized integration with Datadog's APM platform.

自定义/通用 OTEL 端点

🌐 Custom/Generic OTEL Endpoints

针对其他兼容 OTEL 的平台或自定义收集器：

🌐 For other OTEL-compatible platforms or custom collectors:

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

配置选项

🌐 Configuration Options

完成配置

🌐 Complete Configuration

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

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

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

OpenTelemetry 语义约定

🌐 OpenTelemetry Semantic Conventions

该导出器遵循 OpenTelemetry GenAI 语义规范 v1.38.0，确保与可观测性平台的兼容性：

🌐 The exporter follows OpenTelemetry Semantic Conventions for GenAI v1.38.0, ensuring compatibility with observability platforms:

跨度命名

🌐 Span Naming

• 大型语言模型操作：chat {model}
• 工具执行：execute_tool {tool_name}
• 代理运行：invoke_agent {agent_id}
• 工作流运行：invoke_workflow {workflow_id}

关键属性

🌐 Key Attributes

• gen_ai.operation.name - 操作类型（聊天、工具执行等）
• gen_ai.provider.name - 人工智能提供商（OpenAI、Anthropic 等）
• gen_ai.request.model - 型号标识
• gen_ai.input.messages - 提供给模型的聊天记录
• gen_ai.output.messages - 模型返回的消息
• gen_ai.usage.input_tokens - 输入标记数
• gen_ai.usage.output_tokens - 输出标记数
• gen_ai.request.temperature - 采样温度
• gen_ai.response.finish_reasons - 完成原因

协议选择指南

🌐 Protocol Selection Guide

根据你的提供商选择合适的协议包：

🌐 Choose the right protocol package based on your 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
自定义	不同	取决于你的采集器

warning

确保为你的提供商安装正确的协议包。如果安装了错误的包，导出器会提供有用的错误信息。

🌐 Make sure to install the correct protocol package for your provider. The exporter will provide a helpful error message if the wrong package is installed.

故障排除

🌐 Troubleshooting

缺少依赖错误

🌐 Missing Dependency Error

如果你看到类似这样的错误：

🌐 If you see an error like:

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

为你的提供商安装建议的软件包。

🌐 Install the suggested package for your provider.

常见问题

🌐 Common Issues

1. 错误的协议包：请确认你已为你的供应商安装了正确的导出器
2. 无效的端点：请检查端点格式是否符合提供商要求
3. 身份验证失败：请确认 API 密钥和头信息是否正确

相关

🌐 Related

• 追踪概览
• OpenTelemetry 桥
• OpenTelemetry 生成式 AI 语义约定 v1.38.0
• OTEL 导出器参考