SensitiveDataFilter

用於遮蔽 span 欄位中敏感資料的 SpanOutputProcessor。

預設自動套用

Observability 會自動在每個已設定 instance 的 spanOutputProcessors 末端加入 SensitiveDataFilter，確保 secret 在到達 Mastra cloud exporter 等 exporter 前已被遮蔽。此 filter 最後執行（即在所有使用者提供的 processor 之後），所以上游 processor 引入或顯示的敏感資料仍會被遮蔽。除非要自訂選項，否則毋須手動加入。

如要停用或自訂這個自動套用的 filter，請使用 Observability registry 設定中的 sensitiveDataFilter 選項：

import { Observability } from '@mastra/observability'

new Observability({
  configs: {/* ... */},
  // disable the auto-applied filter
  sensitiveDataFilter: false,
  // or customize it
  // sensitiveDataFilter: { sensitiveFields: ['mySecret'], redactionStyle: 'partial' },
})

如果設定的 spanOutputProcessors 已包括 SensitiveDataFilter，便會略過自動套用的 filter，以避免重複遮蔽。預先實例化的 ObservabilityInstance 值不會被修改。如有需要，請自行將 SensitiveDataFilter 加至其 processor。

Constructor

new SensitiveDataFilter(options?: SensitiveDataFilterOptions)

SensitiveDataFilterOptions

interface SensitiveDataFilterOptions {
  /**
   * List of sensitive field names to redact.
   * Matching is case-insensitive and normalizes separators
   * (api-key, api_key, Api Key → apikey).
   * Defaults include: password, token, secret, key, apikey, auth,
   * authorization, bearer, bearertoken, jwt, credential,
   * clientsecret, privatekey, refresh, ssn.
   */
  sensitiveFields?: string[]

  /**
   * The token used for full redaction.
   * Default: "[REDACTED]"
   */
  redactionToken?: string

  /**
   * Style of redaction to use:
   * - "full": always replace with redactionToken
   * - "partial": show 3 characters from the start and end, redact the middle
   * Default: "full"
   */
  redactionStyle?: RedactionStyle
}

RedactionStyle

type RedactionStyle = 'full' | 'partial'

方法

process

process(span: AnySpan): AnySpan

處理 span，篩除以下主要欄位中的敏感資料：attributes、metadata、input、output 及 errorInfo。

傳回： 已遮蔽敏感值的新 span。

shutdown

async shutdown(): Promise<void>

此 processor 毋須清理。

屬性

readonly name = 'sensitive-data-filter';

預設敏感欄位

未提供自訂欄位時：

[
  'password',
  'token',
  'secret',
  'key',
  'apikey',
  'auth',
  'authorization',
  'bearer',
  'bearertoken',
  'jwt',
  'credential',
  'clientsecret',
  'privatekey',
  'refresh',
  'ssn',
]

處理行為

欄位配對

• 不區分大小寫：APIKey、apikey、ApiKey 全部均會配對
• 不區分分隔符：api-key、api_key、apiKey 會視為相同
• 完全配對：標準化後，欄位必須完全相符
  • token 會配對 token、Token、TOKEN
  • token 不會配對 promptTokens 或 tokenCount

遮蔽樣式

完整遮蔽（預設）

所有相符值均以 redactionToken 取代。

部分遮蔽

• 顯示開頭及結尾各 3 個字元
• 6 個或以下字元的值會被完整遮蔽
• 進行部分遮蔽前，非字串值會轉換為字串

錯誤處理

如果篩選欄位失敗，該欄位會被以下內容取代：

{
  error: {
    processor: 'sensitive-data-filter'
  }
}

已處理欄位

filter 會遞迴處理：

• span.attributes - Span metadata 及屬性
• span.metadata - 自訂 metadata
• span.input - 輸入資料
• span.output - 輸出資料
• span.errorInfo - 錯誤資料

可安全處理巢狀物件、陣列及循環參照。