OtelExporter

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

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;
  teamId?: 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>

Exports a tracing event to the configured OTEL backend.

shutdown

async shutdown(): Promise<void>

Flushes pending traces and shuts down the exporter.

Usage Examples

Basic Usage

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

Different providers require different OTEL exporter packages:

Protocol	Required Package	Providers
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, Custom
Zipkin	@opentelemetry/exporter-zipkin	Zipkin collectors

Tags Support

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({
  messages: [{ role: "user", content: "Hello" }],
  tracingOptions: {
    tags: ["production", "experiment-v2", "user-request"],
  },
});

How Tags Are Stored

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

While the OpenTelemetry specification supports native array attributes, many backends (Jaeger, Zipkin, Tempo) have limited array support. JSON strings ensure consistent behavior across all observability platforms.

Related

• OtelExporter Guide - Setup guide with provider configurations
• OtelBridge - For bidirectional OTEL context integration
• Tracing Overview - General tracing concepts