# 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](https://mastra.ai/reference/observability/tracing/configuration):

```typescript
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

```typescript
new SensitiveDataFilter(options?: SensitiveDataFilterOptions)
```

## `SensitiveDataFilterOptions`

```typescript
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`

```typescript
type RedactionStyle = 'full' | 'partial'
```

## Methods

### process

```typescript
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

```typescript
async shutdown(): Promise<void>
```

No cleanup needed for this processor.

## Properties

```typescript
readonly name = 'sensitive-data-filter';
```

## Default sensitive fields

When no custom fields are provided:

```typescript
[
  '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:

```typescript
{
  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.