민감한 데이터 필터

범위 필드에서 민감한 정보를 수정하는 SpanOutputProcessor입니다.

기본적으로 자동 적용됨

Observability는 구성된 모든 인스턴스의 spanOutputProcessors에 SensitiveDataFilter를 자동으로 추가하므로, 비밀 정보는 Mastra Cloud 내보내기 도구 같은 내보내기 도구에 도달하기 전에 수정됩니다. 필터는 마지막에(사용자가 제공한 프로세서 이후에) 실행되므로 업스트림 프로세서가 추가하거나 노출한 민감한 데이터도 수정됩니다. 옵션을 사용자 정의하려는 경우가 아니라면 수동으로 추가할 필요가 없습니다. 자동 적용되는 필터를 비활성화하거나 사용자 정의하려면 Observability 레지스트리 구성의 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가 있으면 이중 수정을 방지하기 위해 자동 적용 필터를 건너뜁니다. 미리 인스턴스화된 ObservabilityInstance 값은 수정되지 않습니다. 필요한 경우 해당 프로세서에 SensitiveDataFilter를 직접 추가하세요.

건설자

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(span: AnySpan): AnySpan

속성, 메타데이터, 입력, 출력 및 errorInfo 등 주요 필드에서 민감한 데이터를 필터링하여 범위를 처리합니다.

보고:민감한 값이 수정된 새 범위입니다.

일시 휴업

async shutdown(): Promise<void>

이 프로세서에는 정리가 필요하지 않습니다.

속성

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자와 마지막 3자를 표시합니다.
• 6자 이하의 값은 완전히 수정되었습니다.
• 문자열이 아닌 값은 부분 수정 전에 문자열로 변환됩니다.

오류 처리

필드 필터링이 실패하면 해당 필드는 다음으로 대체됩니다.

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

처리된 필드

필터는 다음을 재귀적으로 처리합니다.

• span.attributes- 스팬 메타데이터 및 속성
• span.metadata- 맞춤형 메타데이터
• span.input- 입력 데이터
• span.output- 출력 데이터
• span.errorInfo- 오류 정보

중첩된 개체, 배열 및 순환 참조를 안전하게 처리합니다.