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

# 스팬 필터링

범위 필터링은 관측 가능성 구성에서 내보내는 범위를 제어합니다. 이를 사용하여 소음을 줄이거나 스팬당 비용을 낮춥니다. 또한 특정 내보내기 또는 환경에 중요한 범위만 유지할 수도 있습니다.

추적 구성에 대한 간략한 개요는 다음을 참조하세요.[Tracing](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview).

## 사용예

다음 예제에서는 하나의 Observability 구성에서 `excludeSpanTypes`와 `spanFilter`를 함께 사용하는 방법을 보여줍니다.

```ts
import { Mastra } from '@mastra/core'
import { SpanType } from '@mastra/core/observability'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { LangfuseExporter } from '@mastra/langfuse'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-app',
        exporters: [new MastraStorageExporter(), new LangfuseExporter()],
        excludeSpanTypes: [SpanType.MODEL_CHUNK, SpanType.MODEL_STEP],
        spanFilter: span => {
          if (span.type === SpanType.TOOL_CALL && span.attributes?.success) {
            return false
          }

          return true
        },
      },
    },
  }),
})
```

## 구성 옵션

**excludeSpanTypes** (`SpanType[]`): 프로세서와 spanFilter가 실행되기 전에 유형별로 스팬을 삭제합니다. 광범위하고 오버헤드가 적은 필터링에 사용하세요.

**spanFilter** (`(span: AnyExportedSpan) => boolean`): 내보낸 스팬을 받아 유지하려면 true를, 삭제하려면 false를 반환합니다. 필터링이 속성, 메타데이터, 타이밍 또는 엔터티 식별자에 따라 달라질 때 사용하세요.

### `excludeSpanTypes`

최소한의 구성으로 스팬 범주 전체를 제외하려면 `excludeSpanTypes`를 사용하세요. 현재 지원되는 값 세트는 다음을 참조하세요.[`SpanType` enum](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/observability/types/tracing.ts).

```ts
import { SpanType } from '@mastra/core/observability'

excludeSpanTypes: [SpanType.MODEL_CHUNK, SpanType.MODEL_STEP, SpanType.WORKFLOW_SLEEP]
```

### `spanFilter`

필터링이 내보낸 스팬 콘텐츠에 따라 달라지는 경우 다음을 사용하세요.`spanFilter`.

```ts
import { SpanType } from '@mastra/core/observability'

spanFilter: span => {
  if (span.type === SpanType.MODEL_CHUNK) return false
  if (span.type === SpanType.TOOL_CALL && span.attributes?.success) return false

  return true
}
```

추가 예:

```ts
// Only export spans from production
spanFilter: span => span.metadata?.environment === 'production'

// Exclude spans from a specific entity
spanFilter: span => span.entityId !== 'noisy-agent'
```

## 처리순서

범위 필터링은 내보내기 시 다음 순서로 발생합니다.

1. `includeInternalSpans`가 `true`가 아니면 내부 스팬이 삭제됩니다.
2. `excludeSpanTypes`가 일치하는 스팬 유형을 제거합니다.
3. `spanOutputProcessors`가 나머지 스팬을 변환합니다.
4. `spanFilter`가 최종적으로 내보낸 스팬을 유지할지 결정합니다. `spanFilter`에서 오류가 발생하면 Mastra는 조용한 데이터 손실을 방지하기 위해 스팬을 유지하고 오류를 기록합니다.

## 관련된

- [추적 개요](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview)설정과 컨셉을 위한
- [구성 API](https://mastra.zisheng.pro/ko/reference/observability/tracing/configuration)\~을 위한`ObservabilityInstanceConfig`
- [민감한 데이터 필터](https://mastra.zisheng.pro/ko/docs/observability/integrations/processors/sensitive-data-filter)범위 데이터 수정용