SensitiveDataFilter

SpanOutputProcessor qui masque les informations sensibles dans les champs des spans.

Application automatique par défaut

Observability ajoute automatiquement un SensitiveDataFilter aux spanOutputProcessors de chaque instance configurée afin que les secrets soient masqués avant d'atteindre les Exporters, tels que l'Exporter cloud de Mastra. Le filtre s'exécute en dernier, après tous les Processors fournis par l'utilisateur, afin que les données sensibles introduites ou révélées par les Processors en amont soient tout de même masquées. Il n'est pas nécessaire de l'ajouter manuellement, sauf si vous souhaitez personnaliser ses options.

Pour désactiver ou personnaliser le filtre appliqué automatiquement, utilisez l'option sensitiveDataFilter de la configuration du registre Observability :

import { Observability } from '@mastra/observability'

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

Si une configuration inclut déjà un SensitiveDataFilter dans spanOutputProcessors, le filtre automatique est ignoré afin d'éviter un double masquage. Les valeurs ObservabilityInstance préinstanciées ne sont pas modifiées. Si nécessaire, ajoutez vous-même un SensitiveDataFilter à leurs Processors.

Constructeur

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'

Méthodes

process

process(span: AnySpan): AnySpan

Traite un span en filtrant les données sensibles dans ses principaux champs : attributes, metadata, input, output et errorInfo.

Renvoie : un nouveau span dans lequel les valeurs sensibles sont masquées.

shutdown

async shutdown(): Promise<void>

Aucun nettoyage n'est nécessaire pour ce Processor.

Propriétés

readonly name = 'sensitive-data-filter';

Champs sensibles par défaut

Lorsqu'aucun champ personnalisé n'est fourni :

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

Comportement du traitement

Correspondance des champs

• Sans tenir compte de la casse : APIKey, apikey et ApiKey correspondent tous
• Sans tenir compte des séparateurs : api-key, api_key et apiKey sont traités de manière identique
• Correspondance exacte : après normalisation, les champs doivent correspondre exactement
  • token correspond à token, Token et TOKEN
  • token ne correspond ni à promptTokens ni à tokenCount

Styles de masquage

Masquage complet (par défaut)

Toutes les valeurs correspondantes sont remplacées par redactionToken.

Masquage partiel

• Affiche les 3 premiers et les 3 derniers caractères
• Les valeurs de 6 caractères ou moins sont entièrement masquées
• Les valeurs qui ne sont pas des chaînes sont converties en chaînes avant le masquage partiel

Gestion des erreurs

Si le filtrage d'un champ échoue, celui-ci est remplacé par :

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

Champs traités

Le filtre traite récursivement :

• span.attributes - Métadonnées et propriétés du span
• span.metadata - Métadonnées personnalisées
• span.input - Données d'entrée
• span.output - Données de sortie
• span.errorInfo - Informations sur l'erreur

Gère de manière sûre les objets imbriqués, les tableaux et les références circulaires.