Skip to Content

トレーシング

MastraはOpenTelemetry Protocol (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 = { // 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エンドポイントとヘッダーを設定できます:

.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", // endpoint and headers will be picked up from env vars }, }, });

例:SigNoz統合

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

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

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

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

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

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

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

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

  1. next.config.tsでインストルメンテーションフックを有効にする
  2. Mastraテレメトリ設定を構成する
  3. OpenTelemetryエクスポーターを設定する

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