# OpenTelemetry Exporter
[EN] Source: https://mastra.ai/docs/observability/ai-tracing/exporters/otel

:::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](https://opentelemetry.io/docs/specs/semconv/gen-ai/). 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)

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

### For gRPC Providers (Dash0)

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

### For HTTP/JSON Providers (Traceloop)

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

## Provider Configurations

### Dash0

[Dash0](https://www.dash0.com/) provides real-time observability with automatic insights.

```typescript title="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](https://signoz.io/) is an open-source APM alternative with built-in AI tracing support.

```typescript title="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](https://newrelic.com/) provides comprehensive observability with AI monitoring capabilities.

```typescript title="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](https://www.traceloop.com/) specializes in LLM observability with automatic prompt tracking.

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

### Laminar

[Laminar](https://www.lmnr.ai/) provides specialized LLM observability and analytics.

```typescript title="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:

```typescript title="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

```typescript
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](https://opentelemetry.io/docs/specs/semconv/gen-ai/), 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:

| Provider  | Protocol      | Required Package                           |
| --------- | ------------- | ------------------------------------------ |
| Dash0     | gRPC          | `@opentelemetry/exporter-trace-otlp-grpc`  |
| SigNoz    | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
| New Relic | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
| Traceloop | HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`  |
| Laminar   | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
| Custom    | Varies        | Depends 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)

## Related

- [AI Tracing Overview](/docs/observability/ai-tracing/overview)
- [OpenTelemetry GenAI Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
- [OTEL Exporter Reference](/reference/observability/ai-tracing/exporters/otel)


---
title: "AI Tracing | Observability"
description: "Set up AI tracing for Mastra applications"
---