OtelExporter

使用标准化的 GenAI 语义规范将跟踪数据发送到任何兼容 OpenTelemetry 的可观测性平台。

🌐 Sends Tracing data to any OpenTelemetry-compatible observability platform using standardized GenAI semantic conventions.

构造函数

🌐 Constructor

new OtelExporter(config: OtelExporterConfig)

OtelExporterConfig

interface OtelExporterConfig {
  provider?: ProviderConfig;
  timeout?: number;
  batchSize?: number;
  logLevel?: "debug" | "info" | "warn" | "error";
}

提供商配置

🌐 Provider Configurations

Dash0配置

🌐 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>;
}

方法

🌐 Methods

exportTracingEvent

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

将跟踪事件导出到配置的 OTEL 后端。

🌐 Exports a tracing event to the configured OTEL backend.

flush

async flush(): Promise<void>

强制将任何缓冲的跨度刷新到 OTEL 后端，而不关闭导出器。在无服务器环境中非常有用，因为你需要确保在运行时终止之前导出跨度。

🌐 Force flushes any buffered spans to the OTEL backend without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.

shutdown

async shutdown(): Promise<void>

刷新待处理的跟踪并关闭导出器。

🌐 Flushes pending traces and shuts down the exporter.

使用示例

🌐 Usage Examples

零配置（使用环境变量）

🌐 Zero-Config (using environment variables)

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

显式配置

🌐 Explicit Configuration

import { OtelExporter } from "@mastra/otel-exporter";

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

使用自定义端点

🌐 With Custom 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 Requirements

不同的提供商需要不同的OTEL导出器包：

🌐 Different providers require different OTEL exporter packages:

协议	所需软件包	提供商
gRPC	@opentelemetry/exporter-trace-otlp-grpc	Dash0
HTTP/Protobuf	@opentelemetry/exporter-trace-otlp-proto	SigNoz, New Relic, Laminar
HTTP/JSON	@opentelemetry/exporter-trace-otlp-http	Traceloop, 自定义
Zipkin	@opentelemetry/exporter-zipkin	Zipkin 收集器

标签支持

🌐 Tags Support

OtelExporter 支持用于分类和过滤的追踪标签。标签仅应用于根跨度，并作为 mastra.tags 属性存储。

🌐 The OtelExporter supports trace tagging for categorization and filtering. Tags are only applied to root spans and are stored as the mastra.tags attribute.

用法

🌐 Usage

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

标签的存储方式

🌐 How Tags Are Stored

标签作为 JSON 字符串化数组存储在 mastra.tags 的 span 属性中，以实现最大的后端兼容性：

🌐 Tags are stored as a JSON-stringified array in the mastra.tags span attribute for maximum backend compatibility:

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

note

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

相关

🌐 Related

• OtelExporter 指南 - 含供应商配置的设置指南
• OtelBridge - 用于双向 OTEL 上下文集成
• 跟踪概览 - 一般跟踪概念