トレーシング
MastraはOpenTelemetry Protocol (OTLP)をサポートしており、アプリケーションのトレーシングと監視を行うことができます。テレメトリが有効になっている場合、Mastraはエージェント操作、LLMインタラクション、ツール実行、統合呼び出し、ワークフロー実行、データベース操作を含むすべてのコアプリミティブを自動的にトレースします。テレメトリデータは任意のOTELコレクターにエクスポートできます。
基本設定
テレメトリを有効にする簡単な例は以下の通りです:
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 = {
// Name to identify your service in traces (optional)
serviceName?: string;
// Enable/disable telemetry (defaults to true)
enabled?: boolean;
// Control how many traces are sampled
sampling?: {
type: "ratio" | "always_on" | "always_off" | "parent_based";
probability?: number; // For ratio sampling
root?: {
probability: number; // For parent_based sampling
};
};
// Where to send telemetry data
export?: {
type: "otlp" | "console";
endpoint?: string;
headers?: Record<string, string>;
};
};
詳細については、OtelConfig リファレンスドキュメントを参照してください。
環境変数
環境変数を通じてOTLPエンドポイントとヘッダーを設定できます:
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-api-key
その後、設定で:
export const mastra = new Mastra({
// ... other config
telemetry: {
serviceName: "my-app",
enabled: true,
export: {
type: "otlp",
// endpoint and headers will be picked up from env vars
},
},
});
例:SigNoz統合
SigNoz でトレースされたエージェントインタラクションは以下のようになります:

その他のサポートされているプロバイダー
サポートされている可観測性プロバイダーの完全なリストと設定の詳細については、可観測性プロバイダーリファレンスを参照してください。
カスタムインストルメンテーションファイル
/mastra
フォルダにカスタムインストルメンテーションファイルを配置することで、Mastraプロジェクトでカスタムインストルメンテーションファイルを定義できます。Mastraはこれらのファイルを自動的に検出し、デフォルトのインストルメンテーションの代わりにバンドルします。
サポートされているファイルタイプ
Mastraは以下の拡張子を持つインストルメンテーションファイルを探します:
instrumentation.js
instrumentation.ts
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({
url: 'http://localhost:4318/v1/traces',
}),
instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();
Mastraがカスタムインストルメンテーションファイルを見つけると、デフォルトのインストルメンテーションを自動的に置き換え、ビルドプロセス中にバンドルします。
Next.js固有のトレーシング手順
Next.jsを使用している場合、3つの追加設定手順があります:
next.config.ts
でインストルメンテーションフックを有効にする- Mastraテレメトリ設定を構成する
- OpenTelemetryエクスポーターを設定する
実装の詳細については、Next.jsトレーシングガイドを参照してください。