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

# OtelExporter

Trace とログを OpenTelemetry 互換の Observability プラットフォームへ送信します。Trace は標準化された GenAI セマンティック規約を使用します。ログは元の severity とメッセージ本文を維持し、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>
```

exporter をシャットダウンせず、バッファー内のすべての Span を OTEL バックエンドへ強制的にフラッシュします。ランタイム終了前に Span が確実にエクスポートされるようにする必要があるサーバーレス環境で役立ちます。

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

### カスタムエンドポイントを使用

```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 文字列を使用することで、すべての Observability プラットフォームで一貫した動作を実現できます。

## 関連項目

- [OtelExporter ガイド](https://mastra.zisheng.pro/ja/docs/observability/integrations/exporters/otel)：Provider の設定を含むセットアップガイド
- [OtelBridge](https://mastra.zisheng.pro/ja/docs/observability/integrations/bridges/otel)：双方向の OTEL コンテキスト連携
- [Tracing の概要](https://mastra.zisheng.pro/ja/docs/observability/tracing/overview)：Tracing の一般概念