Filtrage des spans

Le filtrage des spans détermine les spans exportés depuis une configuration d’Observability. Utilisez-le pour réduire le bruit ou diminuer les coûts par span. Il permet également de ne conserver que les spans pertinents pour un Exporter ou un environnement précis.

Pour une présentation plus concise de la configuration du traçage, consultez Traçage.

Exemple d’utilisation

L’exemple suivant montre comment combiner excludeSpanTypes et spanFilter dans une même configuration d’Observability :

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
        },
      },
    },
  }),
})

Options de configuration

excludeSpanTypes?:

SpanType[]

Élimine les spans selon leur type avant l’exécution des Processors et de spanFilter. Utilisez cette option pour un filtrage général à faible surcharge.

spanFilter?:

(span: AnyExportedSpan) => boolean

Reçoit le span exporté et renvoie true pour le conserver ou false pour l’éliminer. Utilisez cette option lorsque le filtrage dépend des attributs, des métadonnées, du minutage ou des identifiants d’entité.

excludeSpanTypes

Utilisez excludeSpanTypes lorsque vous souhaitez supprimer des catégories entières de spans avec une configuration minimale.

Pour connaître l’ensemble actuel des valeurs prises en charge, consultez l’énumération SpanType.

src/mastra/index.ts

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

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

spanFilter

Lorsque le filtrage dépend du contenu du span exporté, utilisez 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
}

Exemples supplémentaires :

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'

Ordre de traitement

Le filtrage des spans s’effectue au moment de l’exportation, dans l’ordre suivant :

1. Les spans internes sont éliminés, sauf si includeInternalSpans vaut true.
2. excludeSpanTypes supprime les types de spans correspondants.
3. spanOutputProcessors transforme les spans restants.
4. spanFilter détermine si le span final exporté doit être conservé.

Si spanFilter génère une erreur, Mastra conserve le span et consigne l’erreur afin d’éviter une perte de données silencieuse.

Voir aussi

• Présentation du traçage pour la configuration et les concepts
• API de configuration pour ObservabilityInstanceConfig
• Filtre des données sensibles pour masquer les données des spans