Span 篩選

Span 篩選會控制要從可觀測性設定匯出哪些 span。您可以用它減少雜訊或降低每個 span 的費用，也可以僅保留特定 exporter 或環境所需的 span。

如需較精簡的 tracing 設定概覽，請參閱 Tracing。

使用範例

以下範例示範如何在單一可觀測性設定中結合 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[]

在 processor 與 spanFilter 執行前，依類型捨棄 span。適合用於廣泛、低額外負擔的篩選。

spanFilter?:

(span: AnyExportedSpan) => boolean

接收匯出的 span，傳回 true 以保留，或傳回 false 以捨棄。當篩選條件取決於屬性、metadata、時間或實體識別碼時使用。

excludeSpanTypes

若要用最少設定抑制整類 span，請使用 excludeSpanTypes。

如需目前支援的值，請參閱 SpanType enum。

src/mastra/index.ts

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

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

spanFilter

當篩選條件取決於匯出 span 的內容時，請使用 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'

處理順序

匯出時會依下列順序篩選 span：

1. 除非 includeInternalSpans 為 true，否則捨棄內部 span。
2. excludeSpanTypes 移除相符的 span 類型。
3. spanOutputProcessors 轉換其餘 span。
4. spanFilter 決定是否保留最終匯出的 span。

如果 spanFilter 擲回錯誤，Mastra 會保留該 span 並記錄錯誤，避免無聲的資料遺失。

相關內容

• Tracing 概覽：設定與概念
• 設定 API：ObservabilityInstanceConfig
• 敏感資料篩選器：遮蔽 span 資料