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

# 민감한 데이터 필터

범위 필드에서 민감한 정보를 수정하는 SpanOutputProcessor입니다.

## 기본적으로 자동 적용됨

`Observability`는 구성된 모든 인스턴스의 `spanOutputProcessors`에 `SensitiveDataFilter`를 자동으로 추가하므로, 비밀 정보는 Mastra Cloud 내보내기 도구 같은 내보내기 도구에 도달하기 전에 수정됩니다. 필터는 마지막에(사용자가 제공한 프로세서 이후에) 실행되므로 업스트림 프로세서가 추가하거나 노출한 민감한 데이터도 수정됩니다. 옵션을 사용자 정의하려는 경우가 아니라면 수동으로 추가할 필요가 없습니다. 자동 적용되는 필터를 비활성화하거나 사용자 정의하려면 [`Observability` 레지스트리 구성](https://mastra.zisheng.pro/ko/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`가 있으면 이중 수정을 방지하기 위해 자동 적용 필터를 건너뜁니다. 미리 인스턴스화된 `ObservabilityInstance` 값은 수정되지 않습니다. 필요한 경우 해당 프로세서에 `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'
```

## 행동 양식

### 프로세스

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

속성, 메타데이터, 입력, 출력 및 errorInfo 등 주요 필드에서 민감한 데이터를 필터링하여 범위를 처리합니다.

**보고:**민감한 값이 수정된 새 범위입니다.

### 일시 휴업

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

이 프로세서에는 정리가 필요하지 않습니다.

## 속성

```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자 이하의 값은 완전히 수정되었습니다.
- 문자열이 아닌 값은 부분 수정 전에 문자열로 변환됩니다.

### 오류 처리

필드 필터링이 실패하면 해당 필드는 다음으로 대체됩니다.

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

### 처리된 필드

필터는 다음을 재귀적으로 처리합니다.

- `span.attributes`- 스팬 메타데이터 및 속성
- `span.metadata`- 맞춤형 메타데이터
- `span.input`- 입력 데이터
- `span.output`- 출력 데이터
- `span.errorInfo`- 오류 정보

중첩된 개체, 배열 및 순환 참조를 안전하게 처리합니다.