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

# Span 篩選

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

如需較精簡的 tracing 設定概覽，請參閱 [Tracing](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)。

## 使用範例

以下範例示範如何在單一可觀測性設定中結合 `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、時間或實體識別碼時使用。

### `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-TW/docs/observability/tracing/overview)：設定與概念
- [設定 API](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/configuration)：`ObservabilityInstanceConfig`
- [敏感資料篩選器](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/processors/sensitive-data-filter)：遮蔽 span 資料