設定

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>

具名的可觀測性 instance 設定或預先建立的 instance

configSelector:

ConfigSelector

執行階段設定選擇器函數

sensitiveDataFilter:

boolean | SensitiveDataFilterOptions

控制是否為每個已設定的 instance 自動套用 SensitiveDataFilter。預設為 true。傳入 false 可停用此功能，或傳入 SensitiveDataFilterOptions 物件以自訂欄位、遮蓋 token 或遮蓋樣式。如設定的 spanOutputProcessors 已包含 SensitiveDataFilter，則不會重複加入。預先建立的 instance 不會被修改。

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 輸出處理器

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 資料（輸入／輸出／屬性）序列化的選項

SerializationOptions

maxStringLength?:

number

字串值的長度上限（預設：1024）

maxDepth?:

number

巢狀物件的深度上限（預設：6）

maxArrayLength?:

number

陣列的項目數目上限（預設：50）

maxObjectKeys?:

number

物件的鍵數目上限（預設：50）

logging:

{ enabled?: boolean; level?: LogLevel }

控制將日誌轉送至可觀測性儲存空間。詳情請參閱將日誌記錄至可觀測性儲存空間。

{ enabled?: boolean; level?: LogLevel }

enabled?:

boolean

設為 false 可停用將日誌轉送至可觀測性儲存空間（預設：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
}

Registry 方法

Observability 類別提供以下方法來管理可觀測性 instance：

registerInstance

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

在 registry 中註冊可觀測性 instance。

getInstance

getInstance(name: string): ObservabilityInstance | undefined;

按名稱取得可觀測性 instance。

getDefaultInstance

getDefaultInstance(): ObservabilityInstance | undefined;

傳回預設的可觀測性 instance。

getSelectedInstance

getSelectedInstance(
  options: ConfigSelectorOptions
): ObservabilityInstance | undefined;

傳回由設定選擇器選取的可觀測性 instance，或預設 instance。

listInstances

listInstances(): ReadonlyMap<string, ObservabilityInstance>;

傳回所有已註冊的可觀測性 instance。

hasInstance

hasInstance(name: string): boolean;

檢查可觀測性 instance 是否存在。

setConfigSelector

setConfigSelector(selector: ConfigSelector): void;

設定設定選擇器函數。

unregisterInstance

unregisterInstance(name: string): boolean;

從 registry 移除可觀測性 instance。

clear

clear(): void;

清除所有 instance，但不將其關閉。

shutdown

async shutdown(): Promise<void>;

關閉所有可觀測性 instance 並清除 registry。

另請參閱

文件

• Tracing 概覽：概念及使用指南
• 取樣策略：取樣設定詳情
• 多重設定：使用多個設定

參考

• Tracing 類別：核心 tracing 類別
• 介面：類型定義
• Span 參考：span 生命週期

Exporter

• MastraStorageExporter：將可觀測性事件保留至 Mastra Storage
• MastraPlatformExporter：將可觀測性事件傳送至 Mastra 平台
• Braintrust：Braintrust 整合
• Langfuse：Langfuse 整合
• LangSmith：LangSmith 整合
• Span 篩選：選擇性排除 span