스팬 필터링

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

추적 구성에 대한 간략한 개요는 다음을 참조하세요.Tracing.

사용예

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

src/mastra/index.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.

src/mastra/index.ts

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

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

spanFilter

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

src/mastra/index.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
}

추가 예:

src/mastra/index.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는 조용한 데이터 손실을 방지하기 위해 스팬을 유지하고 오류를 기록합니다.

관련된

• 추적 개요설정과 컨셉을 위한
• 구성 API~을 위한ObservabilityInstanceConfig
• 민감한 데이터 필터범위 데이터 수정용