Configuration

ObservabilityRegistryConfig

interface ObservabilityRegistryConfig {
  default?: { enabled?: boolean }
  configs?: Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>
  configSelector?: ConfigSelector
  sensitiveDataFilter?: boolean | SensitiveDataFilterOptions
}

default:

{ enabled?: boolean }

Active la configuration par défaut avec MastraStorageExporter et MastraPlatformExporter

configs:

Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>

Configurations nommées d’instances d’observabilité ou instances préinstanciées

configSelector:

ConfigSelector

Fonction de sélection de la configuration à l’exécution

sensitiveDataFilter:

boolean | SensitiveDataFilterOptions

Détermine si un SensitiveDataFilter est appliqué automatiquement à chaque instance configurée. La valeur par défaut est true. Transmettez false pour désactiver ce comportement, ou un objet SensitiveDataFilterOptions pour personnaliser les champs, le jeton de masquage ou le style de masquage. Si une configuration contient déjà un SensitiveDataFilter dans spanOutputProcessors, il n’est pas dupliqué. Les instances préinstanciées ne sont pas modifiées.

ObservabilityInstanceConfig

interface ObservabilityInstanceConfig {
  name: string
  serviceName: string
  sampling?: SamplingStrategy
  exporters?: ObservabilityExporter[]
  spanOutputProcessors?: SpanOutputProcessor[]
  includeInternalSpans?: boolean
  excludeSpanTypes?: SpanType[]
  spanFilter?: (span: AnyExportedSpan) => boolean
  requestContextKeys?: string[]
  serializationOptions?: SerializationOptions
  logging?: { enabled?: boolean; level?: LogLevel }
}

name:

string

Identifiant de configuration

serviceName:

string

Nom du service dans les traces

sampling:

SamplingStrategy

Configuration d’échantillonnage (la valeur par défaut est ALWAYS)

exporters:

ObservabilityExporter[]

Exportateurs de données de trace

spanOutputProcessors:

SpanOutputProcessor[]

Processeurs de sortie de spans

includeInternalSpans:

boolean

Inclut les spans internes aux opérations Mastra

excludeSpanTypes:

SpanType[]

Types de spans à exclure de l’exportation. Utile pour réduire le bruit et les coûts sur les plateformes facturant par span. Consultez la référence sur le filtrage des spans pour en savoir plus.

spanFilter:

(span: AnyExportedSpan) => boolean

Fonction de filtrage permettant de contrôler les spans exportés. Renvoyez true pour conserver un span, false pour l’exclure. S’exécute après excludeSpanTypes et spanOutputProcessors. Consultez la référence sur le filtrage des spans pour en savoir plus.

requestContextKeys:

string[]

Clés RequestContext à extraire comme métadonnées (prend en charge la notation par points)

serializationOptions:

SerializationOptions

Options permettant de contrôler la sérialisation des données de span (entrée/sortie/attributs)

SerializationOptions

maxStringLength?:

number

Longueur maximale des valeurs de chaîne (par défaut : 1024)

maxDepth?:

number

Profondeur maximale des objets imbriqués (par défaut : 6)

maxArrayLength?:

number

Nombre maximal d’éléments dans les tableaux (par défaut : 50)

maxObjectKeys?:

number

Nombre maximal de clés dans les objets (par défaut : 50)

logging:

{ enabled?: boolean; level?: LogLevel }

Contrôle le transfert des journaux vers le stockage d’observabilité. Consultez Journaliser dans le stockage d’observabilité pour en savoir plus.

{ enabled?: boolean; level?: LogLevel }

enabled?:

boolean

Définissez cette valeur sur false pour désactiver le transfert des journaux vers le stockage d’observabilité (par défaut : true)

level?:

LogLevel

Niveau minimal de journal à transférer. Une des valeurs 'debug', 'info', 'warn', 'error', 'fatal' (par défaut : 'debug')

SamplingStrategy

type SamplingStrategy =
  | { type: 'always' }
  | { type: 'never' }
  | { type: 'ratio'; probability: number }
  | { type: 'custom'; sampler: (options?: TracingOptions) => boolean }

ConfigSelector

type ConfigSelector = (
  options: ConfigSelectorOptions,
  availableConfigs: ReadonlyMap<string, ObservabilityInstance>,
) => string | undefined

ConfigSelectorOptions

interface ConfigSelectorOptions {
  requestContext?: RequestContext
}

Méthodes du registre

La classe Observability fournit des méthodes permettant de gérer les instances d’observabilité :

registerInstance

registerInstance(
  name: string,
  instance: ObservabilityInstance,
  isDefault?: boolean
): void;

Enregistre une instance d’observabilité dans le registre.

getInstance

getInstance(name: string): ObservabilityInstance | undefined;

Récupère une instance d’observabilité par son nom.

getDefaultInstance

getDefaultInstance(): ObservabilityInstance | undefined;

Renvoie l’instance d’observabilité par défaut.

getSelectedInstance

getSelectedInstance(
  options: ConfigSelectorOptions
): ObservabilityInstance | undefined;

Renvoie l’instance d’observabilité sélectionnée par le sélecteur de configuration ou celle par défaut.

listInstances

listInstances(): ReadonlyMap<string, ObservabilityInstance>;

Renvoie toutes les instances d’observabilité enregistrées.

hasInstance

hasInstance(name: string): boolean;

Vérifie si une instance d’observabilité existe.

setConfigSelector

setConfigSelector(selector: ConfigSelector): void;

Définit la fonction de sélection de configuration.

unregisterInstance

unregisterInstance(name: string): boolean;

Supprime une instance d’observabilité du registre.

clear

clear(): void;

Efface toutes les instances sans les arrêter.

shutdown

async shutdown(): Promise<void>;

Arrête toutes les instances d’observabilité et efface le registre.

Voir aussi

Documentation

• Présentation du traçage : concepts et guide d’utilisation
• Stratégies d’échantillonnage : détails de la configuration de l’échantillonnage
• Configuration multiple : utiliser plusieurs configurations

Référence

• Classes de traçage : classes de traçage principales
• Interfaces : définitions de types
• Référence des spans : cycle de vie des spans

Exportateurs

• MastraStorageExporter : conserve les événements d’observabilité dans Mastra Storage
• MastraPlatformExporter : envoie les événements d’observabilité à la plateforme Mastra
• Braintrust : intégration Braintrust
• Langfuse : intégration Langfuse
• LangSmith : intégration LangSmith
• Filtrage des spans : exclure certains spans de manière sélective