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

# OtelExporter

将 Trace 和日志发送到任何兼容 OpenTelemetry 的可观测性平台。Trace 使用标准化的 GenAI 语义约定；日志会保留其原始严重级别和消息正文，并通过 OTEL 日志记录的原生 Trace 上下文以及 `mastra.traceId` / `mastra.spanId` 属性与 Trace 关联。

## 构造函数

```typescript
new OtelExporter(config: OtelExporterConfig)
```

## `OtelExporterConfig`

```typescript
interface OtelExporterConfig {
  provider?: ProviderConfig
  signals?: {
    traces?: boolean
    logs?: boolean
  }
  timeout?: number
  batchSize?: number
  logLevel?: 'debug' | 'info' | 'warn' | 'error'
}
```

## Provider 配置

### `Dash0Config`

```typescript
interface Dash0Config {
  apiKey?: string
  endpoint?: string
  dataset?: string
}
```

### `SignozConfig`

```typescript
interface SignozConfig {
  apiKey?: string
  region?: 'us' | 'eu' | 'in'
  endpoint?: string
}
```

### `NewRelicConfig`

```typescript
interface NewRelicConfig {
  apiKey?: string
  endpoint?: string
}
```

### `TraceloopConfig`

```typescript
interface TraceloopConfig {
  apiKey?: string
  destinationId?: string
  endpoint?: string
}
```

### `LaminarConfig`

```typescript
interface LaminarConfig {
  apiKey?: string
  endpoint?: string
}
```

### `CustomConfig`

```typescript
interface CustomConfig {
  endpoint: string
  protocol?: 'http/json' | 'http/protobuf' | 'grpc' | 'zipkin'
  headers?: Record<string, string>
}
```

## 方法

### `exportTracingEvent`

```typescript
async exportTracingEvent(event: TracingEvent): Promise<void>
```

将 Tracing 事件导出到所配置的 OTEL 后端。

### flush

```typescript
async flush(): Promise<void>
```

强制将缓冲区中的所有 Span 刷新到 OTEL 后端，而不关闭 Exporter。适用于需要确保运行时终止前已导出 Span 的 serverless 环境。

### shutdown

```typescript
async shutdown(): Promise<void>
```

刷新待处理的 Trace 并关闭 Exporter。

## 用法示例

### 零配置（使用环境变量）

```typescript
import { OtelExporter } from '@mastra/otel-exporter'

// Set SIGNOZ_API_KEY, SIGNOZ_REGION environment variables
const exporter = new OtelExporter({ provider: { signoz: {} } })

// Or for other providers:
// Set DASH0_API_KEY, DASH0_ENDPOINT for Dash0
// Set NEW_RELIC_LICENSE_KEY for New Relic
// Set TRACELOOP_API_KEY for Traceloop
// Set LMNR_PROJECT_API_KEY for Laminar
```

### 显式配置

```typescript
import { OtelExporter } from '@mastra/otel-exporter'

const exporter = new OtelExporter({
  provider: {
    signoz: {
      apiKey: process.env.SIGNOZ_API_KEY,
      region: 'us',
    },
  },
})
```

### 使用自定义 Endpoint

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

## 协议要求

不同 Provider 需要不同的 OTEL Exporter 包。Trace 和日志导出彼此独立：如果只需要 Trace，请仅安装 Trace 包；如果还需要导出日志，请同时安装所选协议对应的 Trace 包和日志包。Zipkin 不支持 OTLP 日志。

| 协议            | Trace 包                                                       | 日志包                                                          |
| ------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
| gRPC          | `@opentelemetry/exporter-trace-otlp-grpc` (+ `@grpc/grpc-js`) | `@opentelemetry/exporter-logs-otlp-grpc` (+ `@grpc/grpc-js`) |
| HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto`                    | `@opentelemetry/exporter-logs-otlp-proto`                    |
| HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`                     | `@opentelemetry/exporter-logs-otlp-http`                     |
| Zipkin        | `@opentelemetry/exporter-zipkin`                              | 不支持                                                          |

## 标签支持

OtelExporter 支持使用 Trace 标签进行分类和筛选。标签仅应用于根 Span，并存储为 `mastra.tags` 属性。

### 用法

```typescript
const result = await agent.generate('Hello', {
  tracingOptions: {
    tags: ['production', 'experiment-v2', 'user-request'],
  },
})
```

### 标签的存储方式

标签以 JSON 字符串化数组的形式存储在 `mastra.tags` Span 属性中，以最大程度兼容后端：

```json
{
  "mastra.tags": "[\"production\",\"experiment-v2\",\"user-request\"]"
}
```

> **备注:** 尽管 OpenTelemetry 规范支持原生数组属性，但许多后端（Jaeger、Zipkin、Tempo）对数组的支持有限。JSON 字符串可确保在所有可观测性平台上保持一致的行为。

## 相关内容

- [OtelExporter 指南](https://mastra.zisheng.pro/docs/observability/integrations/exporters/otel)：包含 Provider 配置的设置指南
- [OtelBridge](https://mastra.zisheng.pro/docs/observability/integrations/bridges/otel)：用于双向 OTEL 上下文集成
- [Tracing 概述](https://mastra.zisheng.pro/docs/observability/tracing/overview)：常规 Tracing 概念