Skip to Content
ドキュメント可観測性トレース

トレーシング

MastraはアプリケーションのトレーシングとモニタリングのためにOpenTelemetryプロトコル（OTLP）をサポートしています。テレメトリが有効になっている場合、Mastraはエージェント操作、LLM連携、ツール実行、インテグレーション呼び出し、ワークフロー実行、データベース操作などのすべてのコアプリミティブを自動的にトレースします。テレメトリデータは任意のOTELコレクターにエクスポートできます。

基本設定

テレメトリを有効にする簡単な例を示します：

mastra.config.ts
export const mastra = new Mastra({
  // ... other config
  telemetry: {
    serviceName: "my-app",
    enabled: true,
    sampling: {
      type: "always_on",
    },
    export: {
      type: "otlp",
      endpoint: "http://localhost:4318", // SigNoz local endpoint
    },
  },
});

設定オプション

テレメトリ設定は以下のプロパティを受け付けます：

type OtelConfig = {
  // トレースでサービスを識別する名前（オプション）
  serviceName?: string;
 
  // テレメトリの有効/無効（デフォルトはtrue）
  enabled?: boolean;
 
  // サンプリングするトレースの数を制御
  sampling?: {
    type: "ratio" | "always_on" | "always_off" | "parent_based";
    probability?: number; // 比率サンプリング用
    root?: {
      probability: number; // 親ベースのサンプリング用
    };
  };
 
  // テレメトリデータの送信先
  export?: {
    type: "otlp" | "console";
    endpoint?: string;
    headers?: Record<string, string>;
  };
};

詳細についてはOtelConfig リファレンスドキュメントを参照してください。

環境変数

環境変数を通じてOTLPエンドポイントとヘッダーを設定できます：

.env
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-api-key

そして設定では：

mastra.config.ts
export const mastra = new Mastra({
  // ... other config
  telemetry: {
    serviceName: "my-app",
    enabled: true,
    export: {
      type: "otlp",
      // エンドポイントとヘッダーは環境変数から取得されます
    },
  },
});

例：SigNoz連携

SigNoz でのトレースされたエージェントインタラクションの例です：

スパン、LLM呼び出し、ツール実行を示すエージェントインタラクショントレース

その他のサポートされているプロバイダー

サポートされている監視プロバイダーの完全なリストとその設定の詳細については、監視プロバイダーリファレンスを参照してください。

Next.js固有のトレーシング手順

Next.jsを使用している場合は、3つの追加設定手順があります：

  1. next.config.tsで計測フックを有効にする
  2. Mastraテレメトリ設定を構成する
  3. OpenTelemetryエクスポーターをセットアップする

実装の詳細については、Next.jsトレーシングガイドを参照してください。

ログ記録概要