Skip to main content

OpenTelemetry Exporter

warning

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

The OpenTelemetry (OTEL) exporter sends your AI 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, Dash0, Traceloop, Laminar, and more.

When to Use OTEL Exporter​

The OTEL exporter is ideal when you need:

  • Platform flexibility - Send traces to any OTEL-compatible backend
  • Standards compliance - Follow OpenTelemetry GenAI semantic conventions
  • Multi-vendor support - Configure once, switch providers easily
  • Enterprise platforms - Integrate with existing observability infrastructure
  • Custom collectors - Send to your own OTEL collector

Installation​

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

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

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

For gRPC Providers (Dash0)​

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

For HTTP/JSON Providers (Traceloop)​

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

Provider Configurations​

Dash0​

Dash0 provides real-time observability with automatic insights.

src/mastra/index.ts
import { Mastra } from "@mastra/core";
import { OtelExporter } from "@mastra/otel-exporter";

export const mastra = new Mastra({
  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

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

SigNoz​

SigNoz is an open-source APM alternative with built-in AI tracing support.

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 provides comprehensive observability with AI monitoring capabilities.

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 specializes in LLM observability with automatic prompt tracking.

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

Laminar​

Laminar provides specialized LLM observability and analytics.

src/mastra/index.ts
new OtelExporter({
  provider: {
    laminar: {
      apiKey: process.env.LMNR_PROJECT_API_KEY,
      // teamId: process.env.LAMINAR_TEAM_ID, // Optional, for backwards compatibility
    },
  },
});

Custom/Generic OTEL Endpoints​

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 Semantic Conventions​

The exporter follows OpenTelemetry Semantic Conventions for GenAI, ensuring compatibility with observability platforms:

Span Naming​

  • LLM Operations: chat {model} or tool_selection {model}
  • Tool Execution: tool.execute {tool_name}
  • Agent Runs: agent.{agent_id}
  • Workflow Runs: workflow.{workflow_id}

Key Attributes​

  • gen_ai.operation.name - Operation type (chat, tool.execute, etc.)
  • gen_ai.system - AI provider (openai, anthropic, etc.)
  • gen_ai.request.model - Model identifier
  • gen_ai.usage.input_tokens - Number of input tokens
  • gen_ai.usage.output_tokens - Number of output tokens
  • gen_ai.request.temperature - Sampling temperature
  • gen_ai.response.finish_reasons - Completion reason

Buffering Strategy​

The exporter buffers spans until a trace is complete:

  1. Collects all spans for a trace
  2. Waits 5 seconds after root span completes
  3. Exports complete trace with preserved parent-child relationships
  4. Ensures no orphaned spans

Protocol Selection Guide​

Choose the right protocol package based on your provider:

ProviderProtocolRequired Package
Dash0gRPC@opentelemetry/exporter-trace-otlp-grpc
SigNozHTTP/Protobuf@opentelemetry/exporter-trace-otlp-proto
New RelicHTTP/Protobuf@opentelemetry/exporter-trace-otlp-proto
TraceloopHTTP/JSON@opentelemetry/exporter-trace-otlp-http
LaminarHTTP/Protobuf@opentelemetry/exporter-trace-otlp-proto
CustomVariesDepends on your collector
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. Wrong protocol package: Verify you installed the correct exporter for your provider
  2. Invalid endpoint: Check endpoint format matches provider requirements
  3. Authentication failures: Verify API keys and headers are correct
  4. No traces appearing: Check that traces complete (root span must end)