設定

ObservabilityRegistryConfig

interface ObservabilityRegistryConfig {
  default?: { enabled?: boolean }
  configs?: Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>
  configSelector?: ConfigSelector
  sensitiveDataFilter?: boolean | SensitiveDataFilterOptions
}

default:

{ enabled?: boolean }

MastraStorageExporter と MastraPlatformExporter を使用するデフォルト設定を有効にします

configs:

Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>

名前付き Observability インスタンス設定、または事前生成済みインスタンス

configSelector:

ConfigSelector

ランタイム設定セレクター関数

sensitiveDataFilter:

boolean | SensitiveDataFilterOptions

設定済みの各インスタンスへ SensitiveDataFilter を自動適用するか制御します。デフォルトは true です。無効にするには false を渡し、フィールド、墨消し token、または墨消し形式をカスタマイズするには SensitiveDataFilterOptions オブジェクトを渡します。設定の spanOutputProcessors に SensitiveDataFilter がすでに含まれる場合、重複して追加されません。事前生成済みインスタンスは変更されません。

ObservabilityInstanceConfig

interface ObservabilityInstanceConfig {
  name: string
  serviceName: string
  sampling?: SamplingStrategy
  exporters?: ObservabilityExporter[]
  spanOutputProcessors?: SpanOutputProcessor[]
  includeInternalSpans?: boolean
  excludeSpanTypes?: SpanType[]
  spanFilter?: (span: AnyExportedSpan) => boolean
  requestContextKeys?: string[]
  serializationOptions?: SerializationOptions
  logging?: { enabled?: boolean; level?: LogLevel }
}

name:

string

設定識別子

serviceName:

string

Trace 内のサービス名

sampling:

SamplingStrategy

サンプリング設定（デフォルト：ALWAYS）

exporters:

ObservabilityExporter[]

Trace データの exporter

spanOutputProcessors:

SpanOutputProcessor[]

Span 出力 processor

includeInternalSpans:

boolean

Mastra の処理内部の Span を含めます

excludeSpanTypes:

SpanType[]

エクスポートから除外する Span タイプ。Span 単位で課金されるプラットフォームのノイズとコストの削減に役立ちます。詳細は Span フィルタリングのリファレンスを参照してください。

spanFilter:

(span: AnyExportedSpan) => boolean

エクスポートする Span を制御するフィルター関数。保持する場合は true、破棄する場合は false を返します。excludeSpanTypes と spanOutputProcessors の後に実行されます。詳細は Span フィルタリングのリファレンスを参照してください。

requestContextKeys:

string[]

メタデータとして抽出する RequestContext キー（ドット記法をサポート）

serializationOptions:

SerializationOptions

Span データ（input/output/attributes）のシリアライズを制御するオプション

SerializationOptions

maxStringLength?:

number

文字列値の最大長（デフォルト：1024）

maxDepth?:

number

ネストしたオブジェクトの最大深度（デフォルト：6）

maxArrayLength?:

number

配列内の最大要素数（デフォルト：50）

maxObjectKeys?:

number

オブジェクト内の最大キー数（デフォルト：50）

logging:

{ enabled?: boolean; level?: LogLevel }

Observability storage へのログ転送を制御します。詳細は Observability storage へのログ記録を参照してください。

{ enabled?: boolean; level?: LogLevel }

enabled?:

boolean

false に設定すると Observability storage へのログ転送を無効にします（デフォルト：true）

level?:

LogLevel

転送する最小ログレベル。'debug'、'info'、'warn'、'error'、'fatal' のいずれか（デフォルト：'debug'）

SamplingStrategy

type SamplingStrategy =
  | { type: 'always' }
  | { type: 'never' }
  | { type: 'ratio'; probability: number }
  | { type: 'custom'; sampler: (options?: TracingOptions) => boolean }

ConfigSelector

type ConfigSelector = (
  options: ConfigSelectorOptions,
  availableConfigs: ReadonlyMap<string, ObservabilityInstance>,
) => string | undefined

ConfigSelectorOptions

interface ConfigSelectorOptions {
  requestContext?: RequestContext
}

レジストリメソッド

Observability クラスは、Observability インスタンスを管理するためのメソッドを提供します。

registerInstance

registerInstance(
  name: string,
  instance: ObservabilityInstance,
  isDefault?: boolean
): void;

Observability インスタンスをレジストリに登録します。

getInstance

getInstance(name: string): ObservabilityInstance | undefined;

名前で Observability インスタンスを取得します。

getDefaultInstance

getDefaultInstance(): ObservabilityInstance | undefined;

デフォルトの Observability インスタンスを返します。

getSelectedInstance

getSelectedInstance(
  options: ConfigSelectorOptions
): ObservabilityInstance | undefined;

設定セレクターで選択された Observability インスタンス、またはデフォルトのインスタンスを返します。

listInstances

listInstances(): ReadonlyMap<string, ObservabilityInstance>;

登録済みのすべての Observability インスタンスを返します。

hasInstance

hasInstance(name: string): boolean;

Observability インスタンスが存在するか確認します。

setConfigSelector

setConfigSelector(selector: ConfigSelector): void;

設定セレクター関数を設定します。

unregisterInstance

unregisterInstance(name: string): boolean;

Observability インスタンスをレジストリから削除します。

clear

clear(): void;

シャットダウンせずにすべてのインスタンスを消去します。

shutdown

async shutdown(): Promise<void>;

すべての Observability インスタンスをシャットダウンし、レジストリを消去します。

関連項目

ドキュメント

• Tracing の概要: 概念と使用ガイド
• サンプリング戦略: サンプリング設定の詳細
• 複数設定のセットアップ: 複数設定の使用

リファレンス

• Tracing クラス: 主要な Tracing クラス
• インターフェース: 型定義
• Spans リファレンス: Span のライフサイクル

Exporters

• MastraStorageExporter: Observability イベントを Mastra Storage に永続化
• MastraPlatformExporter: Observability イベントを Mastra プラットフォームへ送信
• Braintrust: Braintrust 連携
• Langfuse: Langfuse 連携
• LangSmith: LangSmith 連携
• Span フィルタリング: Span を選択的に除外