トレーシング

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

基本設定

テレメトリを有効にする簡単な例は以下の通りです：

mastra.config.ts


export const mastra = new Mastra({
  // ... その他の設定
  telemetry: {
    serviceName: "my-app",
    enabled: true,
    sampling: {
      type: "always_on",
    },
    export: {
      type: "otlp",
      endpoint: "http://localhost:4318", // SigNozローカルエンドポイント
    },
  },
});

設定オプション

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


type OtelConfig = {
  // トレースでサービスを識別する名前（オプション）
  serviceName?: string;
 
  // テレメトリの有効/無効（デフォルトはtrue）
  enabled?: boolean;
 
  // サンプリングするトレースの数を制御
  sampling?: {
    type: "ratio" | "always_on" | "always_off" | "parent_based";
    probability?: number; // 比率サンプリング用
    root?: {
      probability: number; // parent_basedサンプリング用
    };
  };
 
  // テレメトリデータの送信先
  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({
  // ... その他の設定
  telemetry: {
    serviceName: "my-app",
    enabled: true,
    export: {
      type: "otlp",
      // エンドポイントとヘッダーは環境変数から取得されます
    },
  },
});

例：SigNoz統合

SigNoz でトレースされたエージェントインタラクションは以下のようになります：

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

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

カスタムインストルメンテーションファイル

/mastraフォルダにカスタムインストルメンテーションファイルを配置することで、Mastraプロジェクトでカスタムインストルメンテーションファイルを定義できます。Mastraはこれらのファイルを自動的に検出し、デフォルトのインストルメンテーションの代わりにバンドルします。

サポートされているファイルタイプ

Mastraは以下の拡張子を持つインストルメンテーションファイルを探します：

instrumentation.js
instrumentation.ts
instrumentation.mjs

例

/mastra/instrumentation.ts


import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
 
const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
 
sdk.start();

Mastraがカスタムインストルメンテーションファイルを見つけると、自動的にデフォルトのインストルメンテーションを置き換え、ビルドプロセス中にバンドルします。

Mastraサーバー環境外でのトレーシング

mastra startまたはmastra devコマンドを使用する場合、Mastraは自動的にトレーシングに必要なインストルメンテーションファイルをプロビジョニングし、ロードします。ただし、独自のアプリケーション（Mastraサーバー環境外）でMastraを依存関係として使用する場合は、手動でインストルメンテーションファイルを提供する必要があります。

この場合にトレーシングを有効にするには：

設定でMastraテレメトリを有効にします：


export const mastra = new Mastra({
  telemetry: {
    enabled: true,
  },
});

プロジェクトにインストルメンテーションファイル（例：instrumentation.mjs）を作成します：


import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
 
const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter(),
  instrumentations: [getNodeAutoInstrumentations()],
});
 
sdk.start();

OpenTelemetry環境変数を追加します：


OTEL_EXPORTER_OTLP_ENDPOINT=https://api.braintrust.dev/otel
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <Your API Key>, x-bt-parent=project_name:<Your Project Name>"

アプリケーションの前にOpenTelemetry SDKを実行します：


node --import=./instrumentation.mjs --import=@opentelemetry/instrumentation/hook.mjs src/index.js

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

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

next.config.tsでinstrumentationフックを有効にする
Mastraテレメトリ設定を構成する
OpenTelemetryエクスポーターを設定する

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

トレーシング

基本設定

テレメトリを有効にする簡単な例は以下の通りです：

mastra.config.ts


export const mastra = new Mastra({
  // ... その他の設定
  telemetry: {
    serviceName: "my-app",
    enabled: true,
    sampling: {
      type: "always_on",
    },
    export: {
      type: "otlp",
      endpoint: "http://localhost:4318", // SigNozローカルエンドポイント
    },
  },
});

設定オプション

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


type OtelConfig = {
  // トレースでサービスを識別する名前（オプション）
  serviceName?: string;
 
  // テレメトリの有効/無効（デフォルトはtrue）
  enabled?: boolean;
 
  // サンプリングするトレースの数を制御
  sampling?: {
    type: "ratio" | "always_on" | "always_off" | "parent_based";
    probability?: number; // 比率サンプリング用
    root?: {
      probability: number; // parent_basedサンプリング用
    };
  };
 
  // テレメトリデータの送信先
  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({
  // ... その他の設定
  telemetry: {
    serviceName: "my-app",
    enabled: true,
    export: {
      type: "otlp",
      // エンドポイントとヘッダーは環境変数から取得されます
    },
  },
});

例：SigNoz統合

SigNoz でトレースされたエージェントインタラクションは以下のようになります：

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

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

カスタムインストルメンテーションファイル

サポートされているファイルタイプ

Mastraは以下の拡張子を持つインストルメンテーションファイルを探します：

instrumentation.js
instrumentation.ts
instrumentation.mjs

例

/mastra/instrumentation.ts


import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
 
const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
 
sdk.start();

Mastraサーバー環境外でのトレーシング

この場合にトレーシングを有効にするには：

設定でMastraテレメトリを有効にします：


export const mastra = new Mastra({
  telemetry: {
    enabled: true,
  },
});

プロジェクトにインストルメンテーションファイル（例：instrumentation.mjs）を作成します：


import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
 
const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter(),
  instrumentations: [getNodeAutoInstrumentations()],
});
 
sdk.start();

OpenTelemetry環境変数を追加します：


OTEL_EXPORTER_OTLP_ENDPOINT=https://api.braintrust.dev/otel
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <Your API Key>, x-bt-parent=project_name:<Your Project Name>"

アプリケーションの前にOpenTelemetry SDKを実行します：


node --import=./instrumentation.mjs --import=@opentelemetry/instrumentation/hook.mjs src/index.js

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

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

next.config.tsでinstrumentationフックを有効にする
Mastraテレメトリ設定を構成する
OpenTelemetryエクスポーターを設定する

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