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トレーシングガイドを参照してください。

ログ記録概要