OtelExporter

warning

The OtelExporter is currently experimental. APIs and configuration options may change in future releases.

Sends AI 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

exportEvent

async exportEvent(event: AITracingEvent): 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",
});

Span Mapping

The exporter maps Mastra AI spans to OpenTelemetry spans following GenAI semantic conventions:

Span Names

• LLM_GENERATION → chat {model} or tool_selection {model}
• TOOL_CALL → tool.execute {tool_name}
• AGENT_RUN → agent.{agent_id}
• WORKFLOW_RUN → workflow.{workflow_id}

Span Kinds

• Root agent/workflow spans → SERVER
• LLM calls → CLIENT
• Tool calls → INTERNAL or CLIENT
• Workflow steps → INTERNAL

Attributes

The exporter maps to standard OTEL GenAI attributes:

Mastra Attribute	OTEL Attribute
model	gen_ai.request.model
provider	gen_ai.system
inputTokens / promptTokens	gen_ai.usage.input_tokens
outputTokens / completionTokens	gen_ai.usage.output_tokens
temperature	gen_ai.request.temperature
maxOutputTokens	gen_ai.request.max_tokens
finishReason	gen_ai.response.finish_reasons

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

Parent-Child Relationships

The exporter preserves span hierarchy from Mastra's AI tracing:

• Uses parentSpanId directly from Mastra spans
• Maintains correct nesting for agents, workflows, LLM calls, and tools
• Exports complete traces with all relationships intact