SensitiveDataFilter

A SpanOutputProcessor that redacts sensitive information from span fields.

Auto-applied by default

Observability automatically appends a SensitiveDataFilter to every configured instance's spanOutputProcessors so secrets are redacted before they reach exporters such as the Mastra cloud exporter. The filter runs last (after any user-provided processors) so that sensitive data introduced or surfaced by upstream processors is still redacted. You do not need to add it manually unless you want to customize its options.

To opt out or customize the auto-applied filter, use the sensitiveDataFilter option on the Observability registry config:

import { Observability } from '@mastra/observability'

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

If a config already includes a SensitiveDataFilter in spanOutputProcessors, the auto-applied filter is skipped to avoid double redaction. Pre-instantiated ObservabilityInstance values are not modified — add a SensitiveDataFilter to their processors yourself if needed.

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'

Methods

process

process(span: AnySpan): AnySpan

Process a span by filtering sensitive data across its key fields: attributes, metadata, input, output, and errorInfo.

Returns: A new span with sensitive values redacted.

shutdown

async shutdown(): Promise<void>

No cleanup needed for this processor.

Properties

readonly name = 'sensitive-data-filter';

Default sensitive fields

When no custom fields are provided:

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

Processing behavior

Field Matching

• Case-insensitive: APIKey, apikey, ApiKey all match
• Separator-agnostic: api-key, api_key, apiKey are treated identically
• Exact matching: After normalization, fields must match exactly
  • token matches token, Token, TOKEN
  • token doesn't match promptTokens or tokenCount

Redaction Styles

Full Redaction (default)

All matched values replaced with redactionToken.

Partial Redaction

• Shows first 3 and last 3 characters
• Values ≤ 6 characters are fully redacted
• Non-string values are converted to strings before partial redaction

Error handling

If filtering a field fails, the field is replaced with:

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

Processed Fields

The filter recursively processes:

• span.attributes - Span metadata and properties
• span.metadata - Custom metadata
• span.input - Input data
• span.output - Output data
• span.errorInfo - Error information

Handles nested objects, arrays, and circular references safely.