OpenTelemetry exporter

OpenTelemetry（OTEL）exporter は、標準化された OpenTelemetry Semantic Conventions for GenAI を使用して、OTEL 互換の任意の Observability プラットフォームへ Trace とログを送信します。これにより、Datadog、New Relic、SigNoz、MLflow、Latitude、Dash0、Traceloop、Laminar、telemetry.dev など、幅広いプラットフォームとの互換性が確保されます。

双方向の OTEL 統合をお探しですか？

既存の OpenTelemetry instrumentation があり、Mastra の Trace にアクティブな OTEL Span のコンテキストを継承させたい場合は、代わりに OpenTelemetry Bridge を参照してください。

インストール

Provider ごとに特定のプロトコルパッケージが必要です。基本 exporter と、使用する Provider 用のプロトコルパッケージをインストールします。

HTTP/Protobuf Provider の場合（SigNoz、New Relic、Laminar、MLflow、Latitude、telemetry.dev）

npm

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

pnpm

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

Yarn

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

Bun

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

gRPC Provider の場合（Dash0、Datadog）

npm

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

pnpm

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

Yarn

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

Bun

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

HTTP/JSON Provider の場合（Traceloop）

npm

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

pnpm

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

Yarn

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

Bun

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 は、/v1/traces の OTLP エンドポイントを介して Mastra のネイティブ Tracing をサポートします。HTTP/Protobuf で custom Provider を使用し、Trace が正しい MLflow experiment へルーティングされるように experiment header を含めます。

src/mastra/index.ts

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 は、OTLP Trace を取り込むオープンソースの LLM Observability・評価プラットフォームです。HTTP/Protobuf で custom Provider を使用し、Latitude の取り込みエンドポイントを指定して、API キーとプロジェクト slug で認証します。

src/mastra/index.ts

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 で登録するか、セルフホストして、自身の取り込みホストをエンドポイントに指定します。

telemetry.dev

telemetry.dev は OTLP/HTTP protobuf Trace を取り込み、OpenTelemetry GenAI セマンティック規約をモデル、Provider、token、レイテンシ、コストの各フィールドへ正規化します。プロジェクト API キーを指定して custom Provider を使用します。

.env

TELEMETRY_DEV_API_KEY=td_live_...

src/mastra/index.ts

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 は、自動インサイトを備えたリアルタイムの Observability を提供します。

ゼロコンフィグ設定

環境変数を設定し、空の設定で exporter を使用します。

.env

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

# Optional
DASH0_DATASET=production

src/mastra/index.ts

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: {} } })],
      },
    },
  }),
})

明示的な設定

src/mastra/index.ts

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 のエンドポイントはダッシュボードから取得します。形式は ingress.{region}.aws.dash0.com:4317 です。

SigNoz

SigNoz は、Tracing サポートを組み込んだオープンソースの APM 代替製品です。

ゼロコンフィグ設定

.env

# Required
SIGNOZ_API_KEY=your-api-key

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

src/mastra/index.ts

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

明示的な設定

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 は、AI 監視機能を備えた包括的な Observability を提供します。

ゼロコンフィグ設定

.env

# Required
NEW_RELIC_LICENSE_KEY=your-license-key

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

src/mastra/index.ts

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

明示的な設定

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 は、プロンプトの自動追跡を備えた LLM Observability に特化しています。

ゼロコンフィグ設定

.env

# Required
TRACELOOP_API_KEY=your-api-key

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

src/mastra/index.ts

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

明示的な設定

src/mastra/index.ts

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

Laminar

Laminar は、LLM に特化した Observability と分析を提供します。

ゼロコンフィグ設定

.env

# Required
LMNR_PROJECT_API_KEY=your-api-key

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

src/mastra/index.ts

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

明示的な設定

src/mastra/index.ts

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

Laminar ネイティブ exporter

ネイティブの Span パス、metadata、Laminar ダッシュボードでのタグ表示など、Laminar 固有の機能には、専用の @mastra/laminar exporter の使用を検討してください。Laminar プラットフォーム向けに最適化された統合を提供します。

Datadog

Datadog APM は、分散 Tracing を使用したアプリケーションパフォーマンス監視を提供します。OTLP 経由で Datadog へ Trace を送信するには、OTLP 取り込みを有効にした Datadog Agent を実行する必要があります。

Datadog は OTLP の取り込みに gRPC を使用します。正しく動作させるには、明示的な import と bundler の設定が必要です。

src/mastra/index.ts

// 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 の取り込みを有効にする必要があります。datadog.yaml に次の内容を追加します。

otlp_config:
  receiver:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

Datadog Agent をローカルで実行する場合、デフォルトの OTLP エンドポイントは http://localhost:4317 です。

警告

gRPC transport を正しく動作させるには、ファイル先頭での @grpc/grpc-js と @opentelemetry/exporter-trace-otlp-grpc の明示的な import、および bundler.externals の設定が必要です。これらがないと、接続の問題が発生する可能性があります。

Datadog ネイティブ exporter

Span タイプの自動マッピング、LLM Span の分類、gRPC 設定が不要な簡単なセットアップなど、Datadog 固有の機能には、専用の @mastra/datadog exporter の使用を検討してください。Datadog の APM プラットフォーム向けに最適化された統合を提供します。

カスタム／汎用 OTEL エンドポイント

その他の OTEL 互換プラットフォームまたはカスタム collector の場合：

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

シグナル

exporter は2つの OpenTelemetry シグナルを送信します。

• Trace：Mastra の Span。BatchSpanProcessor を介して export されます。
• ログ：Mastra のログイベント。BatchLogRecordProcessor を介して export されます。traceId と spanId を持つログは、OTEL ログレコードのネイティブ Trace コンテキストと mastra.traceId／mastra.spanId 属性の両方を使用して Trace に関連付けられます。そのため、Datadog、Grafana、Honeycomb などのバックエンドは、ログを Trace へ自動的に結合できます。

両方のシグナルはデフォルトで有効になっており、同じ Provider 設定を共有します。ログエンドポイントは、Trace エンドポイントの /v1/traces suffix を /v1/logs に置き換えて生成されます。

シグナルを無効にするには、signals オプションを設定します。

src/mastra/index.ts

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

ログの export には、使用するプロトコルに対応する OTLP ログ exporter パッケージのインストールが必要です。

npm

# 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

# 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

# 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

# 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 パッケージがインストールされていない場合、ログの export は通知なく無効になり、Trace は引き続き動作します。

設定オプション

完全な設定

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 Semantic Conventions for GenAI v1.38.0 に従い、Observability プラットフォームとの互換性を確保します。

Span の命名

• LLM Operation：chat {model}
• Tool の実行：execute_tool {tool_name}
• Agent の実行：invoke_agent {agent_id}
• Workflow の実行：invoke_workflow {workflow_id}

主な属性

• gen_ai.operation.name - Operation タイプ（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 は問題の解決に役立つエラーメッセージを表示します。

トラブルシューティング

依存関係が見つからないエラー

次のようなエラーが表示された場合：

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. 無効なエンドポイント：エンドポイントの形式が Provider の要件に合っていることを確認します
3. 認証エラー：API キーと header が正しいことを確認します

関連情報

• Tracing の概要
• OpenTelemetry Bridge
• OpenTelemetry Semantic Conventions for GenAI v1.38.0
• OTEL exporter リファレンス