設定

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>

具名可觀測性執行個體設定或預先執行個體化的執行個體

configSelector:

ConfigSelector

Runtime 設定 selector 函式

sensitiveDataFilter:

boolean | SensitiveDataFilterOptions

控制是否將 SensitiveDataFilter 自動套用至每個已設定的執行個體。預設為 true。傳入 false 可選擇停用，或傳入 SensitiveDataFilterOptions 物件以自訂欄位、遮蔽 token 或遮蔽樣式。如果某設定的 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 的 filter 函式。傳回 true 以保留，傳回 false 以捨棄。在 excludeSpanTypes 與 spanOutputProcessors 之後執行。如需詳細資訊，請參閱 span 篩選參考。

requestContextKeys:

string[]

要擷取為 metadata 的 RequestContext key（支援點記法）

serializationOptions:

SerializationOptions

控制 span 資料（input／output／attributes）序列化的選項

SerializationOptions

maxStringLength?:

number

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

maxDepth?:

number

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

maxArrayLength?:

number

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

maxObjectKeys?:

number

物件的 key 數量上限（預設：50）

logging:

{ enabled?: boolean; level?: LogLevel }

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

{ enabled?: boolean; level?: LogLevel }

enabled?:

boolean

設為 false 以停用將 log 轉送至可觀測性儲存空間（預設：true）

level?:

LogLevel

要轉送的最低 log 層級。可為 '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 類別提供用於管理可觀測性執行個體的方法：

registerInstance

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

在 registry 中註冊可觀測性執行個體。

getInstance

getInstance(name: string): ObservabilityInstance | undefined;

依名稱擷取可觀測性執行個體。

getDefaultInstance

getDefaultInstance(): ObservabilityInstance | undefined;

傳回預設可觀測性執行個體。

getSelectedInstance

getSelectedInstance(
  options: ConfigSelectorOptions
): ObservabilityInstance | undefined;

傳回由 config selector 選取的可觀測性執行個體，若未選取則傳回預設執行個體。

listInstances

listInstances(): ReadonlyMap<string, ObservabilityInstance>;

傳回所有已註冊的可觀測性執行個體。

hasInstance

hasInstance(name: string): boolean;

檢查可觀測性執行個體是否存在。

setConfigSelector

setConfigSelector(selector: ConfigSelector): void;

設定 config selector 函式。

unregisterInstance

unregisterInstance(name: string): boolean;

從 registry 移除可觀測性執行個體。

clear

clear(): void;

清除所有執行個體，但不將其關閉。

shutdown

async shutdown(): Promise<void>;

關閉所有可觀測性執行個體，並清除 registry。

另請參閱

文件

• Tracing 概覽：概念與使用指南
• 取樣策略：取樣設定詳細資料
• 多設定建置：使用多個設定

參考

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

Exporter

• MastraStorageExporter：將可觀測性事件持久化至 Mastra Storage
• MastraPlatformExporter：將可觀測性事件傳送至 Mastra platform
• Braintrust：Braintrust 整合
• Langfuse：Langfuse 整合
• LangSmith：LangSmith 整合
• Span 篩選：選擇性排除 span