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

# Span 篩選

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

如需較簡短的 Tracing 設定概覽，請參閱 [Tracing](https://mastra.zisheng.pro/zh-HK/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[]`): 在 processor 及 spanFilter 執行前，按類型捨棄 span。適合用於廣泛而額外負擔較低的篩選。

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

### `excludeSpanTypes`

如要以最少設定隱藏整類 span，請使用 `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`

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

## 處理次序

Span 篩選會在匯出時按以下次序進行：

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

如果 `spanFilter` 拋出錯誤，Mastra 會保留該 span 並記錄錯誤，以免資料在沒有提示下遺失。

## 相關內容

- [Tracing 概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)：設定及概念
- [設定 API](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/configuration)：`ObservabilityInstanceConfig`
- [敏感資料 filter](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/processors/sensitive-data-filter)：遮蔽 span 資料