OtelExporter

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

OtelExporter

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