Span 篩選

Span 篩選可控制 observability 設定匯出哪些 span。你可以用它減少雜訊或降低每個 span 的成本，亦可只保留對特定 exporter 或環境重要的 span。

如需較簡短的 Tracing 設定概覽，請參閱 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[]

在 processor 及 spanFilter 執行前，按類型捨棄 span。適合用於廣泛而額外負擔較低的篩選。

spanFilter?:

(span: AnyExportedSpan) => boolean

接收已匯出的 span，傳回 true 代表保留，傳回 false 則代表捨棄。篩選條件取決於屬性、metadata、時間或 entity 識別符時，可使用此選項。

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
• 敏感資料 filter：遮蔽 span 資料