KakaFlow KB

Sensitive Data Filter - Mastra Observability

6 phút đọc

Sensitive Data Filter - Mastra Observability

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-11 · Source: crawler_authoritative

Tình huống

Mastra observability configuration guide for redacting sensitive data (passwords, API keys, tokens) from traces before export, targeting developers configuring telemetry and security teams reviewing observability pipelines.

Insight

The SensitiveDataFilter is a span processor from @mastra/observability that scans attributes, metadata, input, output, and error information across all spans. It redacts values matching field names including: password, token, secret, key, apikey, auth, authorization, bearer, bearertoken, jwt, credential, clientsecret, privatekey, refresh, ssn. Field matching is case-insensitive and separator-agnostic (api-key, api_key, ApiKey normalize to apikey). Configuration accepts sensitiveFields array for custom field names, redactionToken string for replacement text (defaults to ‘[REDACTED]’), and redactionStyle (‘full’ or ‘partial’). Full redaction replaces entire values; partial redaction shows first and last 3 characters (sk-abc123xyz789def456 becomes sk-…456). Values under 7 characters are fully redacted even in partial mode. The filter handles nested objects, arrays, and circular references safely with synchronous processing. On error, fields receive {error: {processor: ‘sensitive-data-filter’}} instead of crashing. Adding SensitiveDataFilter to spanOutputProcessors array in Observability config applies it to all exporters (MastraStorageExporter, MastraPlatformExporter).

Hành động

Add SensitiveDataFilter to spanOutputProcessors in Observability config: import {SensitiveDataFilter, Observability, MastraStorageExporter} from ‘@mastra/observability’, then new Observability({configs: {default: {serviceName: ‘mastra’, exporters: [new MastraStorageExporter()], spanOutputProcessors: [new SensitiveDataFilter()]}}}). For custom fields, pass sensitiveFields array: new SensitiveDataFilter({sensitiveFields: [‘password’, ‘creditCard’, ‘bankAccount’]}). To change redaction behavior, set redactionToken: ‘SENSITIVE’ or redactionStyle: ‘partial’. To disable entirely, set spanOutputProcessors to empty array []. Example healthcare config includes ssn, socialSecurityNumber, medicalRecordNumber, mrn, healthInsuranceNumber. Financial config includes creditCard, ccNumber, cvv, cvc, bankAccount, accountNumber, routingNumber, iban, swift.

Kết quả

Sensitive field values are replaced with [REDACTED] (default) or configured redaction token before spans are exported to any configured exporter (storage, platform). Nested objects and arrays are recursively processed. Fields matching sensitive patterns after normalization (case-insensitive, separator-agnostic) are redacted while non-matching fields pass through unchanged.

Điều kiện áp dụng

Requires @mastra/observability package. Applies to all traces processed through the configured Observability instance.

Nội dung gốc (Original)

Sensitive data filter

The Sensitive Data Filter is a span processor that redacts sensitive information from your traces during the processing pipeline before export. This ensures that passwords, API keys, tokens, and other confidential data never leave your application or get stored in observability platforms.

Default configuration

The Sensitive Data Filter is included in the recommended observability configuration:

import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'
 
export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
        spanOutputProcessors: [
          new SensitiveDataFilter(), // Redacts sensitive fields before export
        ],
      },
    },
  }),
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
})

With the default configuration, the filter redacts these common sensitive field names:

  • password
  • token
  • secret
  • key
  • apikey
  • auth
  • authorization
  • bearer
  • bearertoken
  • jwt
  • credential
  • clientsecret
  • privatekey
  • refresh
  • ssn

Note: Field matching is case-insensitive and normalizes separators. For example, api-key, api_key, and Api Key are all treated as apikey.

How it works

The Sensitive Data Filter processes spans before they’re sent to exporters, scanning through:

  • Attributes - Span metadata and properties
  • Metadata - Custom metadata attached to spans
  • Input - Data sent to agents, tools, and LLMs
  • Output - Responses and results
  • Error Information - Stack traces and error details

When a sensitive field is detected, its value is replaced with [REDACTED] by default. The filter handles nested objects, arrays, and circular references safely.

Custom configuration

You can customize which fields are redacted and how redaction displays:

import { SensitiveDataFilter, MastraStorageExporter, Observability } from '@mastra/observability'
 
export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      production: {
        serviceName: 'my-service',
        exporters: [new MastraStorageExporter()],
        spanOutputProcessors: [
          new SensitiveDataFilter({
            // Add custom sensitive fields
            sensitiveFields: [
              // Default fields
              'password',
              'token',
              'secret',
              'key',
              'apikey',
              // Custom fields for your application
              'creditCard',
              'bankAccount',
              'routingNumber',
              'email',
              'phoneNumber',
              'dateOfBirth',
            ],
            // Custom redaction token
            redactionToken: '***SENSITIVE***',
            // Redaction style
            redactionStyle: 'full', // or 'partial'
          }),
        ],
      },
    },
  }),
})

Redaction styles

The filter supports two redaction styles:

Full Redaction (Default)

Replaces the entire value with a fixed token:

// Before
{
  "apiKey": "sk-abc123xyz789def456",
  "userId": "user_12345"
}
 
// After
{
  "apiKey": "[REDACTED]",
  "userId": "user_12345"
}

Partial Redaction

Shows the first and last 3 characters, useful for debugging without exposing full values:

new SensitiveDataFilter({
  redactionStyle: 'partial',
})
// Before
{
  "apiKey": "sk-abc123xyz789def456",
  "creditCard": "4111111111111111"
}
 
// After
{
  "apiKey": "sk-…456",
  "creditCard": "411…111"
}

Values shorter than 7 characters are fully redacted to prevent information leakage.

Field matching rules

The filter uses intelligent field matching:

  1. Case-Insensitive: APIKey, apikey, and ApiKey are all matched

  2. Separator-Agnostic: api-key, api_key, and apiKey are treated identically

  3. Exact Matching: After normalization, fields must match exactly

    • token matches token, Token, TOKEN
    • token doesn’t match promptTokens or tokenCount

Nested object handling

The filter recursively processes nested structures:

// Before
{
  "user": {
    "id": "12345",
    "credentials": {
      "password": "SuperSecret123!",
      "apiKey": "sk-production-key"
    }
  },
  "config": {
    "auth": {
      "jwt": "eyJhbGciOiJIUzI1NiIs..."
    }
  }
}
 
// After
{
  "user": {
    "id": "12345",
    "credentials": {
      "password": "[REDACTED]",
      "apiKey": "[REDACTED]"
    }
  },
  "config": {
    "auth": {
      "jwt": "[REDACTED]"
    }
  }
}

Performance considerations

The Sensitive Data Filter is designed to be lightweight and efficient:

  • Synchronous Processing: No async operations, minimal latency impact
  • Circular Reference Handling: Safely handles complex object graphs
  • Error Recovery: If filtering fails, the field is replaced with an error marker rather than crashing

Disabling the filter

If you need to disable sensitive data filtering (not recommended for production):

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      debug: {
        serviceName: 'debug-service',
        spanOutputProcessors: [], // No processors, including no SensitiveDataFilter
        exporters: [new MastraStorageExporter()],
      },
    },
  }),
})

Warning: Only disable sensitive data filtering in controlled environments. Never disable it when sending traces to external services or shared storage.

Common use cases

Healthcare Applications

new SensitiveDataFilter({
  sensitiveFields: [
    // HIPAA-related fields
    'ssn',
    'socialSecurityNumber',
    'medicalRecordNumber',
    'mrn',
    'healthInsuranceNumber',
    'diagnosisCode',
    'icd10',
    'prescription',
    'medication',
  ],
})

Financial Services

new SensitiveDataFilter({
  sensitiveFields: [
    // PCI compliance fields
    'creditCard',
    'ccNumber',
    'cardNumber',
    'cvv',
    'cvc',
    'securityCode',
    'expirationDate',
    'expiry',
    'bankAccount',
    'accountNumber',
    'routingNumber',
    'iban',
    'swift',
  ],
})

Error handling

If the filter encounters an error while processing a field, it replaces the field with a safe error marker:

{
  "problematicField": {
    "error": {
      "processor": "sensitive-data-filter"
    }
  }
}

This ensures that processing errors don’t prevent traces from being exported or cause application crashes.

Liên kết

Xem thêm:

Sơ đồ

Liên kết ngược