敏感数据过滤

🌐 Sensitive Data Filter

敏感数据过滤器是一种跨度处理器，用于在导出前的处理管道中隐藏跟踪中的敏感信息。这确保了密码、API 密钥、令牌和其他机密数据不会离开你的应用，也不会存储在可观测性平台中。

🌐 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:

src/mastra/index.ts

import {
  Observability,
  DefaultExporter,
  CloudExporter,
  SensitiveDataFilter,
} from "@mastra/observability";

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: "mastra",
        exporters: [
          new DefaultExporter(),
          new CloudExporter(),
        ],
        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

字段匹配不区分大小写，并会规范分隔符。例如，api-key、api_key 和 Api Key 都被视为 apikey。

🌐 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:

• 属性 - 跨度元数据和属性
• 元数据 - 附加到跨度的自定义元数据
• 输入 - 发送到代理、工具和大语言模型的数据
• 输出 - 回复和结果
• 错误信息 - 堆栈跟踪和错误详情

当检测到敏感字段时，其值默认会被替换为 [REDACTED]。该过滤器可以安全处理嵌套对象、数组和循环引用。

🌐 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 appears:

src/mastra/index.ts

import { SensitiveDataFilter, DefaultExporter, Observability } from "@mastra/observability";

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      production: {
        serviceName: "my-service",
        exporters: [new DefaultExporter()],
        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

显示前3个和后3个字符，便于调试而不暴露完整值：

🌐 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"
}

少于7个字符的值将被完全屏蔽以防止信息泄露。

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

字段匹配规则

🌐 Field Matching Rules

该过滤器使用智能字段匹配：

🌐 The filter uses intelligent field matching:

1. 不区分大小写：APIKey、apikey 和 ApiKey 都可以匹配
2. 分隔符无关：api-key、api_key 和 apiKey 被视为相同
3. 精确匹配：标准化后，字段必须完全匹配
   • token 匹配 token、Token、TOKEN
   • token 不匹配 promptTokens 或 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:

• 同步处理：无异步操作，延迟影响最小
• 循环引用处理：安全地处理复杂的对象图
• 错误恢复：如果过滤失败，该字段会被错误标记替代，而不会导致程序崩溃

禁用过滤器

🌐 Disabling the Filter

如果你需要禁用敏感数据过滤（不建议在生产环境中使用）：

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

src/mastra/index.ts

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

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.

相关

🌐 Related

• SensitiveDataFilter API