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

# 민감한 데이터 필터

민감한 데이터 필터는 내보내기 전 처리 파이프라인 중에 추적에서 중요한 정보를 수정하는 스팬 프로세서입니다. 이렇게 하면 비밀번호, API 키, 토큰 및 기타 기밀 데이터가 애플리케이션을 벗어나지 않거나 관찰 플랫폼에 저장되지 않습니다.

## 기본 구성

민감한 데이터 필터는 권장 관찰 구성에 포함되어 있습니다.

```ts
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',
  }),
})
```

기본 구성을 사용하면 필터는 다음과 같은 일반적인 민감한 필드 이름을 수정합니다.

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

> **노트:** 필드 일치는 대소문자를 구분하지 않으며 구분 기호를 정규화합니다. 예를 들어 `api-key`, `api_key`, `Api Key`는 모두 `apikey`로 처리됩니다.

## 작동 원리

민감한 데이터 필터 프로세스는 수출자에게 전송되기 전에 다음을 통해 검사합니다.

- **속성**- 스팬 메타데이터 및 속성
- **메타데이터**- 스팬에 연결된 커스텀 메타데이터
- **입력**- Agent, Tool 및 LLM으로 전송된 데이터
- **산출**- 대응 및 결과
- **오류 정보**- 스택 추적 및 오류 세부 정보

민감한 필드가 감지되면 기본적으로 해당 값을 `[REDACTED]`로 대체합니다. 필터는 중첩 객체, 배열 및 순환 참조를 안전하게 처리합니다.

## 맞춤 구성

수정되는 필드와 수정 표시 방법을 사용자 정의할 수 있습니다.

```ts
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'
          }),
        ],
      },
    },
  }),
})
```

## 교정 스타일

필터는 두 가지 수정 스타일을 지원합니다.

### 전체 교정(기본값)

전체 값을 고정 토큰으로 바꿉니다.

```jsonc
// Before
{
  "apiKey": "sk-abc123xyz789def456",
  "userId": "user_12345"
}

// After
{
  "apiKey": "[REDACTED]",
  "userId": "user_12345"
}
```

### 부분 편집

전체 값을 노출하지 않고 디버깅하는 데 유용한 첫 번째와 마지막 3자를 표시합니다.

```ts
new SensitiveDataFilter({
  redactionStyle: 'partial',
})
```

```json
// Before
{
  "apiKey": "sk-abc123xyz789def456",
  "creditCard": "4111111111111111"
}

// After
{
  "apiKey": "sk-…456",
  "creditCard": "411…111"
}
```

정보 유출을 방지하기 위해 7자보다 짧은 값은 완전히 수정됩니다.

## 필드 일치 규칙

필터는 지능형 필드 일치를 사용합니다.

1. **대소문자 구분 없음**: `APIKey`, `apikey`, `ApiKey`가 모두 일치합니다.

2. **구분 기호 무관**: `api-key`, `api_key`, `apiKey`를 동일하게 처리합니다.

3. **정확한 일치**: 정규화 후 필드가 정확히 일치해야 합니다.

   - `token`은 `token`, `Token`, `TOKEN`과 일치합니다.
   - `token`은 `promptTokens` 또는 `tokenCount`와 일치하지 않습니다.

## 중첩 객체 처리

필터는 중첩된 구조를 재귀적으로 처리합니다.

```json
// 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]"
    }
  }
}
```

## 성능 고려사항

민감한 데이터 필터는 가볍고 효율적으로 설계되었습니다.

- **동기 처리**: 비동기 작업이 없으며 지연 시간에 미치는 영향이 최소화됩니다.
- **순환 참조 처리**: 복잡한 객체 그래프를 안전하게 처리합니다.
- **오류 복구**: 필터링이 실패하면 필드가 충돌이 아닌 오류 표시로 대체됩니다.

## 필터 비활성화

민감한 데이터 필터링을 비활성화해야 하는 경우(프로덕션에는 권장되지 않음):

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

> **경고:** 통제된 환경에서만 민감한 데이터 필터링을 비활성화하세요. 외부 서비스나 공유 저장소로 추적을 보낼 때 이 기능을 비활성화하지 마십시오.

## 일반적인 사용 사례

### 의료 애플리케이션

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

### 금융 서비스

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

## 오류 처리

필터가 필드를 처리하는 동안 오류가 발생하면 해당 필드를 안전한 오류 표시기로 바꿉니다.

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

결과적으로 처리 오류로 인해 추적 내보내기가 차단되지 않거나 애플리케이션 충돌이 발생합니다.

## 관련된

- [SensitiveDataFilter API](https://mastra.zisheng.pro/ko/reference/observability/tracing/processors/sensitive-data-filter)