> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# SensitiveDataFilter

span のフィールドから機密情報をマスキングする SpanOutputProcessor です。

## デフォルトで自動適用

`Observability` は、設定された各インスタンスの `spanOutputProcessors` に `SensitiveDataFilter` を自動的に追加します。これにより、機密情報は Mastra cloud exporter などの exporter に届く前にマスキングされます。この filter は最後（ユーザー指定の processor の後）に実行されるため、先行する processor が追加または露出させた機密データもマスキングされます。オプションをカスタマイズする場合を除き、手動で追加する必要はありません。

自動適用される filter を無効化またはカスタマイズするには、[`Observability` registry 設定](https://mastra.zisheng.pro/ja/reference/observability/tracing/configuration)の `sensitiveDataFilter` オプションを使用します。

```typescript
import { Observability } from '@mastra/observability'

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

設定の `spanOutputProcessors` に `SensitiveDataFilter` がすでに含まれている場合、二重のマスキングを避けるため、自動適用される filter はスキップされます。事前にインスタンス化された `ObservabilityInstance` の値は変更されません。必要に応じて、その processor に `SensitiveDataFilter` を追加してください。

## コンストラクター

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

## メソッド

### process

```typescript
process(span: AnySpan): AnySpan
```

attributes、metadata、input、output、errorInfo の主要フィールド全体で機密データを filter し、span を処理します。

**戻り値：** 機密値がマスキングされた新しい span。

### shutdown

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

この processor ではクリーンアップは不要です。

## プロパティ

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

## デフォルトの機密フィールド

カスタムフィールドが指定されていない場合：

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

## 処理動作

### フィールドの照合

- **大文字と小文字を区別しない**：`APIKey`、`apikey`、`ApiKey` はすべて一致します

- **区切り文字を区別しない**：`api-key`、`api_key`、`apiKey` は同一として扱われます

- **完全一致**：正規化後、フィールドは完全に一致する必要があります

  - `token` は `token`、`Token`、`TOKEN` に一致します
  - `token` は `promptTokens` や `tokenCount` には一致しません

### マスキング形式

#### 完全マスキング（デフォルト）

一致したすべての値を redactionToken に置き換えます。

#### 部分マスキング

- 先頭 3 文字と末尾 3 文字を表示します
- 6 文字以下の値は完全にマスキングされます
- 文字列以外の値は、部分マスキングの前に文字列へ変換されます

### エラー処理

フィールドの filtering に失敗した場合、そのフィールドは次の値に置き換えられます。

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

### 処理対象フィールド

filter は次のフィールドを再帰的に処理します。

- `span.attributes` - span のメタデータとプロパティ
- `span.metadata` - カスタムメタデータ
- `span.input` - 入力データ
- `span.output` - 出力データ
- `span.errorInfo` - エラー情報

ネストされた object、配列、循環参照を安全に処理します。