> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# OpenTelemetry exporter

OpenTelemetry（OTEL）exporter 使用标准化的 [OpenTelemetry GenAI 语义约定](https://opentelemetry.io/docs/specs/semconv/gen-ai/)，将 Trace 和日志发送到任何兼容 OTEL 的可观测性平台。这确保了与 Datadog、New Relic、SigNoz、MLflow、Latitude、Dash0、Traceloop、Laminar、telemetry.dev 等平台的广泛兼容性。

> **需要双向 OTEL 集成？:** 如果已有 OpenTelemetry 埋点，并希望 Mastra Trace 从活跃 OTEL span 继承上下文，请改用 [OpenTelemetry Bridge](https://mastra.zisheng.pro/docs/observability/integrations/bridges/otel)。

## 安装

每个 Provider 都需要特定的协议软件包。请安装基础 exporter 和 Provider 对应的协议软件包：

### 对于 HTTP/Protobuf Provider（SigNoz、New Relic、Laminar、MLflow、Latitude、telemetry.dev）

**npm**:

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

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**Bun**:

```bash
bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

### 对于 `gRPC` Provider（Dash0、Datadog）

**npm**:

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

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
```

**Bun**:

```bash
bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
```

### 对于 HTTP/JSON Provider（Traceloop）

**npm**:

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

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
```

**Bun**:

```bash
bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
```

## 环境变量

所有 Provider 都支持通过环境变量进行零配置设置。设置相应变量后，exporter 会自动使用它们：

| Provider  | 环境变量                                                                        |
| --------- | --------------------------------------------------------------------------- |
| Dash0     | `DASH0_API_KEY`（必需）、`DASH0_ENDPOINT`（必需）、`DASH0_DATASET`（可选）                |
| SigNoz    | `SIGNOZ_API_KEY`（必需）、`SIGNOZ_REGION`（可选）、`SIGNOZ_ENDPOINT`（可选）              |
| New Relic | `NEW_RELIC_LICENSE_KEY`（必需）、`NEW_RELIC_ENDPOINT`（可选）                        |
| Traceloop | `TRACELOOP_API_KEY`（必需）、`TRACELOOP_DESTINATION_ID`、`TRACELOOP_ENDPOINT`（可选） |
| Laminar   | `LMNR_PROJECT_API_KEY`（必需）、`LAMINAR_ENDPOINT`（可选）                           |

## Provider 配置

### MLflow

[MLflow](https://mlflow.org/docs/latest/genai/tracing/integrations/listing/mastra) 通过 `/v1/traces` 上的 OTLP endpoint 原生支持 Mastra Tracing。请使用带 HTTP/Protobuf 的 `custom` Provider，并包含 experiment header，使 Trace 路由到正确的 MLflow experiment：

```typescript
new OtelExporter({
  provider: {
    custom: {
      endpoint: `${process.env.MLFLOW_TRACKING_URI}/v1/traces`,
      protocol: 'http/protobuf',
      headers: {
        'x-mlflow-experiment-id': process.env.MLFLOW_EXPERIMENT_ID,
      },
    },
  },
})
```

### Latitude

[Latitude](https://latitude.so) 是一个开源 LLM 可观测性与评估平台，可接收 OTLP Trace。请使用带 HTTP/Protobuf 的 `custom` Provider，指向 Latitude ingestion endpoint，并使用 API key 和项目 slug 进行身份验证：

```typescript
new OtelExporter({
  provider: {
    custom: {
      endpoint: 'https://ingest.latitude.so/v1/traces',
      protocol: 'http/protobuf',
      headers: {
        Authorization: `Bearer ${process.env.LATITUDE_API_KEY}`,
        'X-Latitude-Project': process.env.LATITUDE_PROJECT,
      },
    },
  },
})
```

在 [console.latitude.so](https://console.latitude.so/login) 注册，或进行自托管并将 endpoint 指向自己的 ingestion host。

### telemetry.dev

[telemetry.dev](https://telemetry.dev) 接收 OTLP/HTTP protobuf Trace，并将 OpenTelemetry GenAI 语义约定标准化为模型、Provider、token、延迟和成本字段。请使用带项目 API key 的 `custom` Provider：

```bash
TELEMETRY_DEV_API_KEY=td_live_...
```

```typescript
new OtelExporter({
  provider: {
    custom: {
      endpoint: 'https://ingest.telemetry.dev/v1/traces',
      protocol: 'http/protobuf',
      headers: {
        Authorization: `Bearer ${process.env.TELEMETRY_DEV_API_KEY}`,
      },
    },
  },
})
```

### Dash0

[Dash0](https://www.dash0.com/) 提供具备自动洞察的实时可观测性。

#### 零配置设置

设置环境变量，并使用空配置的 exporter：

```bash
# Required
DASH0_API_KEY=your-api-key
DASH0_ENDPOINT=ingress.us-west-2.aws.dash0.com:4317

# Optional
DASH0_DATASET=production
```

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelExporter } from '@mastra/otel-exporter'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      otel: {
        serviceName: 'my-service',
        exporters: [new OtelExporter({ provider: { dash0: {} } })],
      },
    },
  }),
})
```

#### 显式配置

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelExporter } from '@mastra/otel-exporter'

export const mastra = new Mastra({
  observability: new 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',
            },
          }),
        ],
      },
    },
  }),
})
```

> **信息:** 从 Dash0 仪表板获取 endpoint。其格式应为 `ingress.{region}.aws.dash0.com:4317`。

### `SigNoz`

[SigNoz](https://signoz.io/) 是一个内置 Tracing 支持的开源 APM 替代方案。

#### 零配置设置

```bash
# Required
SIGNOZ_API_KEY=your-api-key

# Optional
SIGNOZ_REGION=us  # 'us' | 'eu' | 'in'
SIGNOZ_ENDPOINT=https://my-signoz.example.com  # For self-hosted
```

```typescript
new OtelExporter({ provider: { signoz: {} } })
```

#### 显式配置

```typescript
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/) 提供带 AI 监控功能的完整可观测性。

#### 零配置设置

```bash
# Required
NEW_RELIC_LICENSE_KEY=your-license-key

# Optional
NEW_RELIC_ENDPOINT=https://otlp.eu01.nr-data.net  # For EU region
```

```typescript
new OtelExporter({ provider: { newrelic: {} } })
```

#### 显式配置

```typescript
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/) 专注于 LLM 可观测性和自动 prompt 跟踪。

#### 零配置设置

```bash
# Required
TRACELOOP_API_KEY=your-api-key

# Optional
TRACELOOP_DESTINATION_ID=my-destination
TRACELOOP_ENDPOINT=https://custom.traceloop.com
```

```typescript
new OtelExporter({ provider: { traceloop: {} } })
```

#### 显式配置

```typescript
new OtelExporter({
  provider: {
    traceloop: {
      apiKey: process.env.TRACELOOP_API_KEY,
      destinationId: 'my-destination', // Optional
    },
  },
})
```

### Laminar

[Laminar](https://laminar.sh/) 提供专业的 LLM 可观测和分析功能。

#### 零配置设置

```bash
# Required
LMNR_PROJECT_API_KEY=your-api-key

# Optional
LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces
```

```typescript
new OtelExporter({ provider: { laminar: {} } })
```

#### 显式配置

```typescript
new OtelExporter({
  provider: {
    laminar: {
      apiKey: process.env.LMNR_PROJECT_API_KEY,
    },
  },
})
```

> **Laminar 原生 exporter:** 如果需要原生 span path、元数据和标签在 Laminar 仪表板中的呈现等 Laminar 专用功能，请考虑使用专用的 [`@mastra/laminar`](https://mastra.zisheng.pro/docs/observability/integrations/exporters/laminar) exporter。它针对 Laminar 平台提供了优化集成。

### Datadog

[Datadog](https://www.datadoghq.com/) APM 提供带分布式 Tracing 的应用性能监控。要通过 OTLP 将 Trace 发送到 Datadog，需要运行启用了 OTLP ingestion 的 Datadog Agent。

Datadog 使用 gRPC 接收 OTLP 数据，因此需要显式 import 和 [bundler 配置](https://mastra.zisheng.pro/reference/configuration)才能正常工作：

```typescript
// Explicitly import gRPC dependencies for the bundler
import '@grpc/grpc-js'
import '@opentelemetry/exporter-trace-otlp-grpc'
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelExporter, type ExportProtocol } from '@mastra/otel-exporter'

export const mastra = new Mastra({
  // Add grpc-js to externals so it's handled at runtime
  bundler: {
    externals: ['@grpc/grpc-js'],
  },
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-service',
        exporters: [
          new OtelExporter({
            provider: {
              custom: {
                endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317',
                protocol: (process.env.OTEL_EXPORTER_OTLP_PROTOCOL || 'grpc') as ExportProtocol,
                headers: {},
              },
            },
          }),
        ],
      },
    },
  }),
})
```

> **信息:** Datadog Agent 必须配置为启用 OTLP ingestion。将以下内容添加到 `datadog.yaml`：
>
> ```yaml
> otlp_config:
>   receiver:
>     protocols:
>       grpc:
>         endpoint: 0.0.0.0:4317
> ```
>
> 本地运行 Datadog Agent 时，默认 OTLP endpoint 为 `http://localhost:4317`。

> **注意:** 文件顶部对 `@grpc/grpc-js` 和 `@opentelemetry/exporter-trace-otlp-grpc` 的显式 import，以及 [`bundler.externals`](https://mastra.zisheng.pro/reference/configuration) 配置，都是 gRPC transport 正常工作的必要条件。缺少这些设置可能会遇到连接问题。

> **Datadog 原生 exporter:** 如果需要自动 span 类型映射、LLM span 分类，以及无需 gRPC 配置的简化设置等 Datadog 专用功能，请考虑使用专用的 [`@mastra/datadog`](https://mastra.zisheng.pro/docs/observability/integrations/exporters/datadog) exporter。它针对 Datadog APM 平台提供了优化集成。

### 自定义/通用 OTEL endpoint

对于其他兼容 OTEL 的平台或自定义 collector：

```typescript
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,
      },
    },
  },
})
```

## 信号

Exporter 会发送两种 OpenTelemetry 信号：

- Trace：Mastra span，通过 `BatchSpanProcessor` 导出。
- 日志：Mastra 日志事件，通过 `BatchLogRecordProcessor` 导出。带有 `traceId` 和 `spanId` 的日志会同时使用 OTEL 日志记录的原生 Trace 上下文和 `mastra.traceId` / `mastra.spanId` 属性与 Trace 关联，使 Datadog、Grafana 和 Honeycomb 等后端能够自动将日志与 Trace 连接。

两种信号默认启用，并共享相同的 Provider 配置。日志 endpoint 通过将 Trace endpoint 的 `/v1/traces` 后缀替换为 `/v1/logs` 派生。

要禁用某个信号，请设置 `signals` 选项：

```typescript
new OtelExporter({
  provider: {/* ... */},
  signals: {
    traces: true, // default
    logs: false, // disable log export
  },
})
```

日志导出需要安装与协议匹配的 OTLP 日志 exporter 软件包：

**npm**:

```bash
# HTTP/JSON
npm install @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
npm install @opentelemetry/exporter-logs-otlp-proto
# gRPC
npm install @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js
```

**pnpm**:

```bash
# HTTP/JSON
pnpm add @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
pnpm add @opentelemetry/exporter-logs-otlp-proto
# gRPC
pnpm add @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js
```

**Yarn**:

```bash
# HTTP/JSON
yarn add @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
yarn add @opentelemetry/exporter-logs-otlp-proto
# gRPC
yarn add @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js
```

**Bun**:

```bash
# HTTP/JSON
bun add @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
bun add @opentelemetry/exporter-logs-otlp-proto
# gRPC
bun add @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js
```

如果未安装匹配的日志 exporter 软件包，日志导出会静默禁用，而 Trace 仍会继续工作。

## 配置选项

### 完整配置

```typescript
new OtelExporter({
  // Provider configuration (required)
  provider: {
    // Use one of: dash0, signoz, newrelic, traceloop, laminar, custom
  },

  // Per-signal toggles. Both default to true.
  signals: {
    traces: true,
    logs: true,
  },

  // Export configuration
  timeout: 30000, // Export timeout in milliseconds
  batchSize: 100, // Number of spans/logs per batch

  // Debug options
  logLevel: 'info', // 'debug' | 'info' | 'warn' | 'error'
})
```

## `OpenTelemetry` 语义约定

Exporter 遵循 [OpenTelemetry GenAI 语义约定 v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai)，确保与可观测性平台兼容：

### Span 命名

- **LLM 操作**：`chat {model}`
- **Tool 执行**：`execute_tool {tool_name}`
- **Agent 运行**：`invoke_agent {agent_id}`
- **Workflow 运行**：`invoke_workflow {workflow_id}`

### 关键属性

- `gen_ai.operation.name`——操作类型（chat、tool.execute 等）
- `gen_ai.provider.name`——AI Provider（openai、anthropic 等）
- `gen_ai.request.model`——模型标识符
- `gen_ai.input.messages`——提供给模型的聊天历史
- `gen_ai.output.messages`——模型返回的消息
- `gen_ai.usage.input_tokens`——输入 token 数量
- `gen_ai.usage.output_tokens`——输出 token 数量
- `gen_ai.request.temperature`——采样 temperature
- `gen_ai.response.finish_reasons`——完成原因

## 协议选择指南

根据 Provider 选择正确的协议软件包：

| Provider  | 协议            | 必需软件包                                      |
| --------- | ------------- | ------------------------------------------ |
| Dash0     | gRPC          | `@opentelemetry/exporter-trace-otlp-grpc`  |
| Datadog   | 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    | 视情况而定         | 取决于 collector                              |

> **注意:** 请务必为 Provider 安装正确的协议软件包。如果安装了错误的软件包，exporter 会提供有帮助的错误消息。

## 故障排除

### 缺少依赖错误

如果看到如下错误：

```text
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
```

请安装为 Provider 建议的软件包。

### 常见问题

1. **协议软件包错误**：确认已为 Provider 安装正确的 exporter
2. **Endpoint 无效**：检查 endpoint 格式是否符合 Provider 要求
3. **身份验证失败**：确认 API key 和 header 正确

## 相关内容

- [Tracing 概览](https://mastra.zisheng.pro/docs/observability/tracing/overview)
- [OpenTelemetry Bridge](https://mastra.zisheng.pro/docs/observability/integrations/bridges/otel)
- [OpenTelemetry GenAI 语义约定 v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai)
- [OTEL Exporter 参考](https://mastra.zisheng.pro/reference/observability/tracing/exporters/otel)