AI トレーシング

AI トレーシングは、アプリケーション内の AI 関連処理に特化した監視とデバッグ機能を提供します。有効化すると、Mastra がエージェントの実行、LLM の生成、ツール呼び出し、ワークフローの各ステップに対し、AI 固有のコンテキストとメタデータを含むトレースを自動的に作成します。

従来のアプリケーショントレーシングとは異なり、AI トレーシングは AI パイプラインの把握に特化しています。トークン使用量、モデルのパラメータ、ツール実行の詳細、会話フローを記録し、問題のデバッグ、パフォーマンス最適化、本番環境における AI システムの挙動の理解を容易にします。

AI トレースは次の方法で作成します:

エクスポーターを設定して、Langfuse などのオブザーバビリティプラットフォームへトレースデータを送信する
サンプリング戦略を設定して、収集対象のトレースを制御する
エージェントやワークフローを実行する — Mastra が詳細な AI トレーシングで自動的にインストルメントします

これにより、最小限のセットアップで AI 運用を高い粒度で可視化でき、より信頼性が高く、観測可能性に優れた AI アプリケーションの構築に役立ちます。

実験的機能

AI トレーシングは @mastra/core 0.14.0 から利用可能で、現在は実験段階です。API は今後のリリースで変更される可能性があります。

標準的なトレーシングとの違い

AI Tracing は Mastra の既存のOpenTelemetry ベースのトレーシングを補完しますが、目的は異なります。

機能	標準トレーシング	AI Tracing
焦点	アプリケーションのインフラ	AI の処理のみ
データ形式	OpenTelemetry に準拠	プロバイダー独自（Langfuse など）
タイミング	バッチエクスポート	デバッグ向けのリアルタイム
メタデータ	汎用的なスパン属性	AI 固有（トークン、モデル、ツール）

現在の状況

対応エクスポーター:

✅ Langfuse - リアルタイムモード対応のフルサポート
✅ Braintrust - 初期リリース
🔄 OpenTelemetry - 近日対応予定

既知の制限事項:

Mastra Playground のトレースは、引き続き従来のトレーシングシステムを使用しています
API は試験的で、変更される可能性があります

最新情報は GitHub issue #6773 をご覧ください。

基本設定

AI Tracing を有効化するシンプルな例を紹介します：

src/mastra/index.ts


import { LangfuseExporter } from '@mastra/langfuse';
 
export const mastra = new Mastra({
  // ... other config
  observability: {
    instances: {
      langfuse: {
        serviceName: 'my-service',
        exporters: [
          new LangfuseExporter({
            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
            secretKey: process.env.LANGFUSE_SECRET_KEY,
            baseUrl: process.env.LANGFUSE_BASE_URL, // 任意 - 既定では Langfuse Cloud
            realtime: true,
          }),
        ],
      },
    },
  },
});

設定オプション

AI トレーシングの設定では次のプロパティを指定できます:


type AITracingConfig = {
  // トレーシングインスタンス名とその設定のマップ
  instances: Record<string, AITracingInstanceConfig | MastraAITracing>;
 
  // 使用するトレーシングインスタンスを選択するための任意の関数
  selector?: TracingSelector;
};
 
type AITracingInstanceConfig = {
  // トレース上でサービスを識別するための名前
  serviceName: string;
 
  // 収集（サンプリング）するトレース数を制御
  sampling?: {
    type: "always" | "never" | "ratio" | "custom";
    probability?: number; // 比率サンプリング用 (0.0 〜 1.0)
    sampler?: (context: TraceContext) => boolean; // カスタムサンプリング用
  };
 
  // トレースデータを送信するエクスポーターの配列
  exporters?: AITracingExporter[];
 
  // エクスポート前にスパンを変換するプロセッサの配列
  processors?: AISpanProcessor[];
};

サンプリング設定

収集してエクスポートするトレースを制御します:

src/mastra/index.ts


export const mastra = new Mastra({
  observability: {
    instances: {
      langfuse: {
        serviceName: 'my-service',
        // すべてのトレースをサンプリング（デフォルト）
        sampling: { type: 'always' },
        exporters: [langfuseExporter],
      },
 
      development: {
        serviceName: 'dev-service',
        // トレースの 10% をサンプリング
        sampling: {
          type: 'ratio',
          probability: 0.1
        },
        exporters: [langfuseExporter],
      },
 
      custom: {
        serviceName: 'custom-service',
        // カスタムサンプリングロジック
        sampling: {
          type: 'custom',
          sampler: (context) => {
            // 特定ユーザーからのリクエストのみをトレース
            return context.metadata?.userId === 'debug-user';
          }
        },
        exporters: [langfuseExporter],
      },
    },
  },
});

エクスポーター

Langfuse エクスポーター

インストール


npm install @mastra/langfuse

設定

Langfuse エクスポーターは次のオプションを受け付けます:


type LangfuseExporterConfig = {
  // Langfuse の API 認証情報（必須）
  publicKey?: string;
  secretKey?: string;
  
  // Langfuse のホスト URL（任意・既定は Langfuse Cloud）
  baseUrl?: string;
  
  // トレースを即時に可視化するためのリアルタイムモードを有効化
  realtime?: boolean; // 既定は false
 
  // Langfuse クライアントに渡す追加オプション
  options?: any;
};

基本設定

mastra.config.ts


import { LangfuseExporter } from '@mastra/langfuse';
 
export const mastra = new Mastra({
  observability: {
    instances: {
      langfuse: {
        serviceName: process.env.SERVICE_NAME || 'mastra-app',
        sampling: { type: 'always' },
        exporters: [
          new LangfuseExporter({
            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
            secretKey: process.env.LANGFUSE_SECRET_KEY,
            baseUrl: process.env.LANGFUSE_BASE_URL, // 任意
            realtime: process.env.NODE_ENV === 'development',
          }),
        ],
      },
    },
  },
});

リアルタイム vs バッチモード

Langfuse エクスポーターは次の2つのモードをサポートします:

バッチモード（既定）

トレースはバッファリングされ、定期的に送信される
本番環境で高いパフォーマンス
トレースの表示にわずかな遅延が生じる場合がある

リアルタイムモード

各トレースイベントを即時にフラッシュ
開発やデバッグに最適
Langfuse ダッシュボードで即座に可視化


new LangfuseExporter({
  // ... 他の設定
  realtime: process.env.NODE_ENV === 'development',
})

Braintrust エクスポーター

Braintrust エクスポーターはトレースデータを Braintrust に送信し、AI の評価とモニタリングを行います。

インストール


npm install @mastra/braintrust

設定


type BraintrustExporterConfig = {
  // Braintrust の API キー（必須）
  apiKey?: string;
 
  // 任意のカスタムエンドポイント
  endpoint?: string;
 
  // 診断メッセージ用のログレベル（既定: 'warn'）
  logLevel?: 'debug' | 'info' | 'warn' | 'error';
 
  // Braintrust に渡す追加のチューニングパラメーター
  tuningParameters?: Record<string, any>;
};

基本設定

src/mastra/index.ts


import { BraintrustExporter } from '@mastra/braintrust';
 
export const mastra = new Mastra({
  observability: {
    instances: {
      braintrust: {
        serviceName: 'my-service',
        exporters: [
          new BraintrustExporter({
            apiKey: process.env.BRAINTRUST_API_KEY,
            endpoint: process.env.BRAINTRUST_ENDPOINT, // 任意
          }),
        ],
      },
    },
  },
});

複数インスタンスの設定

複数のトレーシングインスタンスを設定し、セレクターで使用するものを選択できます:

mastra.config.ts


export const mastra = new Mastra({
  observability: {
    instances: {
      production: {
        serviceName: 'prod-service',
        sampling: { type: 'ratio', probability: 0.1 },
        exporters: [prodLangfuseExporter],
      },
      development: {
        serviceName: 'dev-service',
        sampling: { type: 'always' },
        exporters: [devLangfuseExporter],
      },
    },
    selector: (context, availableTracers) => {
      // デバッグセッションでは development のトレーサーを使用
      if (context.runtimeContext?.get('debug') === 'true') {
        return 'development';
      }
      return 'production';
    },
  },
});

スパンの種類と属性

AI Tracing は、さまざまな AI 処理に対して自動的にスパンを作成します。Mastra は次のスパンタイプをサポートしています。

エージェントのオペレーションタイプ

AGENT_RUN - エージェントの実行全体（開始から終了まで）
LLM_GENERATION - プロンプトと応答を伴う個別のモデル呼び出し
TOOL_CALL - 入出力を伴う関数/ツールの実行
MCP_TOOL_CALL - Model Context Protocol のツール実行
GENERIC - カスタム処理

ワークフローのオペレーションタイプ

WORKFLOW_RUN - ワークフローの実行全体（開始から終了まで）
WORKFLOW_STEP - 個々のステップ処理
WORKFLOW_CONDITIONAL - 条件分岐ブロック
WORKFLOW_CONDITIONAL_EVAL - 個々の条件評価
WORKFLOW_PARALLEL - 並列実行ブロック
WORKFLOW_LOOP - ループ実行ブロック
WORKFLOW_SLEEP - スリープ/遅延処理
WORKFLOW_WAIT_EVENT - イベント待機処理

主要な属性

各スパンタイプには関連する属性が含まれます：

エージェントスパン：エージェント ID、インストラクション、利用可能なツール、最大ステップ数
LLM スパン：モデル名、プロバイダー、トークン使用量、パラメータ、終了理由
ツールスパン：ツール ID、ツール種別、成功ステータス
ワークフロースパン：ステップ/ワークフロー ID、ステータス情報

スパンへのカスタムメタデータの追加

ワークフローステップやツール呼び出しで利用できる tracingContext.currentSpan を使って、スパンにカスタムメタデータを追加できます。これは、APIのステータスコード、ユーザーID、パフォーマンスメトリクスなどの追加情報を追跡するのに役立ちます。


execute: async ({ inputData, tracingContext }) => {
  const response = await fetch(inputData.endpoint, {
    method: 'POST',
    body: JSON.stringify(inputData.payload),
  });
 
  // 現在のスパンにカスタムメタデータを追加
  tracingContext.currentSpan?.update({
    metadata: {
      apiStatusCode: response.status,
      responseHeaders: Object.fromEntries(response.headers.entries()),
      endpoint: inputData.endpoint,
    }
  });
 
  const data = await response.json();
  return { data, statusCode: response.status };
}

子スパンの作成

ワークフローのステップやツール内で特定の処理を追跡するために、子スパンを作成できます。これにより、実行時に何が起きているかをより細かく可視化できます。


execute: async ({ input, tracingContext }) => {
  // データベースクエリ用の子スパンを作成
  const querySpan = tracingContext.currentSpan?.createChildSpan({
    type: 'generic',
    name: 'database-query',
    input: {
      query: input.query,
      params: input.params,
    }
  });
 
  try {
    const results = await db.query(input.query, input.params);
 
    // 結果で子スパンを更新して終了
    querySpan?.end({
      output: results.data,
      metadata: {
        rowsReturned: results.length,
        success: true,
      }
    });
 
    return { results, rowCount: results.length };
  } catch (error) {
    // 子スパンにエラーを記録
    querySpan?.error({ error });
    throw error;
  }
}

スパンプロセッサとデータフィルタリング

スパンプロセッサを使用すると、スパンデータがオブザーバビリティプラットフォームにエクスポートされる前に、修正やフィルタリングを行えます。これは、算出フィールドの追加、機密情報のマスキング、データ形式の変換に役立ちます。

組み込みの SensitiveDataFilter

Mastra には、スパンデータから機密フィールドを自動的にマスキングする SensitiveDataFilter プロセッサが含まれています。デフォルトで有効になっており、一般的な機密フィールド名をスキャンします:

src/mastra/index.ts


import { LangfuseExporter } from '@mastra/langfuse';
import { SensitiveDataFilter } from '@mastra/core/ai-tracing';
 
export const mastra = new Mastra({
  observability: {
    instances: {
      langfuse: {
        serviceName: 'my-service',
        exporters: [new LangfuseExporter({ /* config */ })],
        // SensitiveDataFilter is included by default, but you can customize it
        processors: [
          new SensitiveDataFilter([
            'password', 'token', 'secret', 'key', 'apiKey',
            'auth', 'authorization', 'bearer', 'jwt',
            'credential', 'sessionId',
            // Add your custom sensitive fields
            'ssn', 'creditCard', 'bankAccount'
          ])
        ],
      },
    },
  },
});

SensitiveDataFilter は次の領域で一致するフィールドを自動的にマスキングします:

スパン属性
スパンメタデータ
入出力データ
エラー情報

フィールドの照合は大文字小文字を区別せずに行われ、入れ子のオブジェクトも再帰的に処理されます。

カスタムプロセッサ

独自のスパン変換ロジックを実装するために、カスタムプロセッサを作成できます:


import type { AISpanProcessor, AnyAISpan } from '@mastra/core/ai-tracing';
 
export class PerformanceEnrichmentProcessor implements AISpanProcessor {
  name = 'performance-enrichment';
 
  process(span: AnyAISpan): AnyAISpan | null {
    const modifiedSpan = { ...span };
 
    // 算出したパフォーマンス指標を追加
    if (span.startTime && span.endTime) {
      const duration = span.endTime.getTime() - span.startTime.getTime();
 
      modifiedSpan.metadata = {
        ...span.metadata,
        durationMs: duration,
        performanceCategory: duration < 100 ? 'fast' : duration < 1000 ? 'medium' : 'slow',
      };
    }
 
    // 実行環境のコンテキストを追加
    modifiedSpan.metadata = {
      ...modifiedSpan.metadata,
      environment: process.env.NODE_ENV || 'unknown',
      region: process.env.AWS_REGION || 'unknown',
    };
 
    return modifiedSpan;
  }
 
  async shutdown(): Promise<void> {
    // 必要に応じてクリーンアップ
  }
}
 
// Mastra の設定で使用
export const mastra = new Mastra({
  observability: {
    instances: {
      langfuse: {
        serviceName: 'my-service',
        exporters: [new LangfuseExporter({ /* config */ })],
        processors: [
          new SensitiveDataFilter(),
          new PerformanceEnrichmentProcessor(),
        ],
      },
    },
  },
});

プロセッサは定義された順序で実行され、各プロセッサは直前のプロセッサの出力を受け取ります。

AI トレーシング

AI トレースは次の方法で作成します:

エクスポーターを設定して、Langfuse などのオブザーバビリティプラットフォームへトレースデータを送信する
サンプリング戦略を設定して、収集対象のトレースを制御する
エージェントやワークフローを実行する — Mastra が詳細な AI トレーシングで自動的にインストルメントします

実験的機能

AI トレーシングは @mastra/core 0.14.0 から利用可能で、現在は実験段階です。API は今後のリリースで変更される可能性があります。

標準的なトレーシングとの違い

AI Tracing は Mastra の既存のOpenTelemetry ベースのトレーシングを補完しますが、目的は異なります。

機能	標準トレーシング	AI Tracing
焦点	アプリケーションのインフラ	AI の処理のみ
データ形式	OpenTelemetry に準拠	プロバイダー独自（Langfuse など）
タイミング	バッチエクスポート	デバッグ向けのリアルタイム
メタデータ	汎用的なスパン属性	AI 固有（トークン、モデル、ツール）

現在の状況

対応エクスポーター:

✅ Langfuse - リアルタイムモード対応のフルサポート
✅ Braintrust - 初期リリース
🔄 OpenTelemetry - 近日対応予定

既知の制限事項:

Mastra Playground のトレースは、引き続き従来のトレーシングシステムを使用しています
API は試験的で、変更される可能性があります

最新情報は GitHub issue #6773 をご覧ください。

基本設定

AI Tracing を有効化するシンプルな例を紹介します：

src/mastra/index.ts


import { LangfuseExporter } from '@mastra/langfuse';
 
export const mastra = new Mastra({
  // ... other config
  observability: {
    instances: {
      langfuse: {
        serviceName: 'my-service',
        exporters: [
          new LangfuseExporter({
            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
            secretKey: process.env.LANGFUSE_SECRET_KEY,
            baseUrl: process.env.LANGFUSE_BASE_URL, // 任意 - 既定では Langfuse Cloud
            realtime: true,
          }),
        ],
      },
    },
  },
});

設定オプション

AI トレーシングの設定では次のプロパティを指定できます:


type AITracingConfig = {
  // トレーシングインスタンス名とその設定のマップ
  instances: Record<string, AITracingInstanceConfig | MastraAITracing>;
 
  // 使用するトレーシングインスタンスを選択するための任意の関数
  selector?: TracingSelector;
};
 
type AITracingInstanceConfig = {
  // トレース上でサービスを識別するための名前
  serviceName: string;
 
  // 収集（サンプリング）するトレース数を制御
  sampling?: {
    type: "always" | "never" | "ratio" | "custom";
    probability?: number; // 比率サンプリング用 (0.0 〜 1.0)
    sampler?: (context: TraceContext) => boolean; // カスタムサンプリング用
  };
 
  // トレースデータを送信するエクスポーターの配列
  exporters?: AITracingExporter[];
 
  // エクスポート前にスパンを変換するプロセッサの配列
  processors?: AISpanProcessor[];
};

サンプリング設定

収集してエクスポートするトレースを制御します:

src/mastra/index.ts


export const mastra = new Mastra({
  observability: {
    instances: {
      langfuse: {
        serviceName: 'my-service',
        // すべてのトレースをサンプリング（デフォルト）
        sampling: { type: 'always' },
        exporters: [langfuseExporter],
      },
 
      development: {
        serviceName: 'dev-service',
        // トレースの 10% をサンプリング
        sampling: {
          type: 'ratio',
          probability: 0.1
        },
        exporters: [langfuseExporter],
      },
 
      custom: {
        serviceName: 'custom-service',
        // カスタムサンプリングロジック
        sampling: {
          type: 'custom',
          sampler: (context) => {
            // 特定ユーザーからのリクエストのみをトレース
            return context.metadata?.userId === 'debug-user';
          }
        },
        exporters: [langfuseExporter],
      },
    },
  },
});

エクスポーター

Langfuse エクスポーター

インストール


npm install @mastra/langfuse

設定

Langfuse エクスポーターは次のオプションを受け付けます:


type LangfuseExporterConfig = {
  // Langfuse の API 認証情報（必須）
  publicKey?: string;
  secretKey?: string;
  
  // Langfuse のホスト URL（任意・既定は Langfuse Cloud）
  baseUrl?: string;
  
  // トレースを即時に可視化するためのリアルタイムモードを有効化
  realtime?: boolean; // 既定は false
 
  // Langfuse クライアントに渡す追加オプション
  options?: any;
};

基本設定

mastra.config.ts


import { LangfuseExporter } from '@mastra/langfuse';
 
export const mastra = new Mastra({
  observability: {
    instances: {
      langfuse: {
        serviceName: process.env.SERVICE_NAME || 'mastra-app',
        sampling: { type: 'always' },
        exporters: [
          new LangfuseExporter({
            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
            secretKey: process.env.LANGFUSE_SECRET_KEY,
            baseUrl: process.env.LANGFUSE_BASE_URL, // 任意
            realtime: process.env.NODE_ENV === 'development',
          }),
        ],
      },
    },
  },
});

リアルタイム vs バッチモード

Langfuse エクスポーターは次の2つのモードをサポートします:

バッチモード（既定）

トレースはバッファリングされ、定期的に送信される
本番環境で高いパフォーマンス
トレースの表示にわずかな遅延が生じる場合がある

リアルタイムモード

各トレースイベントを即時にフラッシュ
開発やデバッグに最適
Langfuse ダッシュボードで即座に可視化


new LangfuseExporter({
  // ... 他の設定
  realtime: process.env.NODE_ENV === 'development',
})

Braintrust エクスポーター

Braintrust エクスポーターはトレースデータを Braintrust に送信し、AI の評価とモニタリングを行います。

インストール


npm install @mastra/braintrust

設定


type BraintrustExporterConfig = {
  // Braintrust の API キー（必須）
  apiKey?: string;
 
  // 任意のカスタムエンドポイント
  endpoint?: string;
 
  // 診断メッセージ用のログレベル（既定: 'warn'）
  logLevel?: 'debug' | 'info' | 'warn' | 'error';
 
  // Braintrust に渡す追加のチューニングパラメーター
  tuningParameters?: Record<string, any>;
};

基本設定

src/mastra/index.ts


import { BraintrustExporter } from '@mastra/braintrust';
 
export const mastra = new Mastra({
  observability: {
    instances: {
      braintrust: {
        serviceName: 'my-service',
        exporters: [
          new BraintrustExporter({
            apiKey: process.env.BRAINTRUST_API_KEY,
            endpoint: process.env.BRAINTRUST_ENDPOINT, // 任意
          }),
        ],
      },
    },
  },
});

複数インスタンスの設定

複数のトレーシングインスタンスを設定し、セレクターで使用するものを選択できます:

mastra.config.ts


export const mastra = new Mastra({
  observability: {
    instances: {
      production: {
        serviceName: 'prod-service',
        sampling: { type: 'ratio', probability: 0.1 },
        exporters: [prodLangfuseExporter],
      },
      development: {
        serviceName: 'dev-service',
        sampling: { type: 'always' },
        exporters: [devLangfuseExporter],
      },
    },
    selector: (context, availableTracers) => {
      // デバッグセッションでは development のトレーサーを使用
      if (context.runtimeContext?.get('debug') === 'true') {
        return 'development';
      }
      return 'production';
    },
  },
});

スパンの種類と属性

AI Tracing は、さまざまな AI 処理に対して自動的にスパンを作成します。Mastra は次のスパンタイプをサポートしています。

エージェントのオペレーションタイプ

AGENT_RUN - エージェントの実行全体（開始から終了まで）
LLM_GENERATION - プロンプトと応答を伴う個別のモデル呼び出し
TOOL_CALL - 入出力を伴う関数/ツールの実行
MCP_TOOL_CALL - Model Context Protocol のツール実行
GENERIC - カスタム処理

ワークフローのオペレーションタイプ

WORKFLOW_RUN - ワークフローの実行全体（開始から終了まで）
WORKFLOW_STEP - 個々のステップ処理
WORKFLOW_CONDITIONAL - 条件分岐ブロック
WORKFLOW_CONDITIONAL_EVAL - 個々の条件評価
WORKFLOW_PARALLEL - 並列実行ブロック
WORKFLOW_LOOP - ループ実行ブロック
WORKFLOW_SLEEP - スリープ/遅延処理
WORKFLOW_WAIT_EVENT - イベント待機処理

主要な属性

各スパンタイプには関連する属性が含まれます：

エージェントスパン：エージェント ID、インストラクション、利用可能なツール、最大ステップ数
LLM スパン：モデル名、プロバイダー、トークン使用量、パラメータ、終了理由
ツールスパン：ツール ID、ツール種別、成功ステータス
ワークフロースパン：ステップ/ワークフロー ID、ステータス情報

スパンへのカスタムメタデータの追加


execute: async ({ inputData, tracingContext }) => {
  const response = await fetch(inputData.endpoint, {
    method: 'POST',
    body: JSON.stringify(inputData.payload),
  });
 
  // 現在のスパンにカスタムメタデータを追加
  tracingContext.currentSpan?.update({
    metadata: {
      apiStatusCode: response.status,
      responseHeaders: Object.fromEntries(response.headers.entries()),
      endpoint: inputData.endpoint,
    }
  });
 
  const data = await response.json();
  return { data, statusCode: response.status };
}

子スパンの作成


execute: async ({ input, tracingContext }) => {
  // データベースクエリ用の子スパンを作成
  const querySpan = tracingContext.currentSpan?.createChildSpan({
    type: 'generic',
    name: 'database-query',
    input: {
      query: input.query,
      params: input.params,
    }
  });
 
  try {
    const results = await db.query(input.query, input.params);
 
    // 結果で子スパンを更新して終了
    querySpan?.end({
      output: results.data,
      metadata: {
        rowsReturned: results.length,
        success: true,
      }
    });
 
    return { results, rowCount: results.length };
  } catch (error) {
    // 子スパンにエラーを記録
    querySpan?.error({ error });
    throw error;
  }
}

スパンプロセッサとデータフィルタリング

組み込みの SensitiveDataFilter

src/mastra/index.ts


import { LangfuseExporter } from '@mastra/langfuse';
import { SensitiveDataFilter } from '@mastra/core/ai-tracing';
 
export const mastra = new Mastra({
  observability: {
    instances: {
      langfuse: {
        serviceName: 'my-service',
        exporters: [new LangfuseExporter({ /* config */ })],
        // SensitiveDataFilter is included by default, but you can customize it
        processors: [
          new SensitiveDataFilter([
            'password', 'token', 'secret', 'key', 'apiKey',
            'auth', 'authorization', 'bearer', 'jwt',
            'credential', 'sessionId',
            // Add your custom sensitive fields
            'ssn', 'creditCard', 'bankAccount'
          ])
        ],
      },
    },
  },
});

SensitiveDataFilter は次の領域で一致するフィールドを自動的にマスキングします:

スパン属性
スパンメタデータ
入出力データ
エラー情報

フィールドの照合は大文字小文字を区別せずに行われ、入れ子のオブジェクトも再帰的に処理されます。

カスタムプロセッサ

独自のスパン変換ロジックを実装するために、カスタムプロセッサを作成できます:


import type { AISpanProcessor, AnyAISpan } from '@mastra/core/ai-tracing';
 
export class PerformanceEnrichmentProcessor implements AISpanProcessor {
  name = 'performance-enrichment';
 
  process(span: AnyAISpan): AnyAISpan | null {
    const modifiedSpan = { ...span };
 
    // 算出したパフォーマンス指標を追加
    if (span.startTime && span.endTime) {
      const duration = span.endTime.getTime() - span.startTime.getTime();
 
      modifiedSpan.metadata = {
        ...span.metadata,
        durationMs: duration,
        performanceCategory: duration < 100 ? 'fast' : duration < 1000 ? 'medium' : 'slow',
      };
    }
 
    // 実行環境のコンテキストを追加
    modifiedSpan.metadata = {
      ...modifiedSpan.metadata,
      environment: process.env.NODE_ENV || 'unknown',
      region: process.env.AWS_REGION || 'unknown',
    };
 
    return modifiedSpan;
  }
 
  async shutdown(): Promise<void> {
    // 必要に応じてクリーンアップ
  }
}
 
// Mastra の設定で使用
export const mastra = new Mastra({
  observability: {
    instances: {
      langfuse: {
        serviceName: 'my-service',
        exporters: [new LangfuseExporter({ /* config */ })],
        processors: [
          new SensitiveDataFilter(),
          new PerformanceEnrichmentProcessor(),
        ],
      },
    },
  },
});

プロセッサは定義された順序で実行され、各プロセッサは直前のプロセッサの出力を受け取ります。