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

# Interfaces

## Interfaces principales

### `ObservabilityInstance`

Interface principale de l’observabilité.

```typescript
interface ObservabilityInstance {
  /** Get current configuration */
  getConfig(): Readonly<Required<ObservabilityInstanceConfig>>

  /** Get all exporters */
  getExporters(): readonly ObservabilityExporter[]

  /** Get all span output processors */
  getSpanOutputProcessors(): readonly SpanOutputProcessor[]

  /** Get the logger instance (for exporters and other components) */
  getLogger(): IMastraLogger

  /** Start a new span of a specific SpanType */
  startSpan<TType extends SpanType>(options: StartSpanOptions<TType>): Span<TType>

  /** Force flush any buffered spans without shutting down */
  flush(): Promise<void>

  /** Shutdown observability and clean up resources */
  shutdown(): Promise<void>
}
```

### `SpanTypeMap`

Association des types de spans aux interfaces d’attributs correspondantes.

```typescript
interface SpanTypeMap {
  AGENT_RUN: AgentRunAttributes
  WORKFLOW_RUN: WorkflowRunAttributes
  MODEL_GENERATION: ModelGenerationAttributes
  MODEL_STEP: ModelStepAttributes
  MODEL_CHUNK: ModelChunkAttributes
  TOOL_CALL: ToolCallAttributes
  CLIENT_TOOL_CALL: ClientToolCallAttributes
  PROVIDER_TOOL_CALL: ProviderToolCallAttributes
  MCP_TOOL_CALL: MCPToolCallAttributes
  PROCESSOR_RUN: ProcessorRunAttributes
  WORKFLOW_STEP: WorkflowStepAttributes
  WORKFLOW_CONDITIONAL: WorkflowConditionalAttributes
  WORKFLOW_CONDITIONAL_EVAL: WorkflowConditionalEvalAttributes
  WORKFLOW_PARALLEL: WorkflowParallelAttributes
  WORKFLOW_LOOP: WorkflowLoopAttributes
  WORKFLOW_SLEEP: WorkflowSleepAttributes
  WORKFLOW_WAIT_EVENT: WorkflowWaitEventAttributes
  GENERIC: AIBaseAttributes
}
```

Cette association définit l’interface d’attributs utilisée pour chaque type de span lors de la création ou du traitement des spans.

### Span

Interface Span utilisée en interne pour le tracing.

```typescript
interface Span<TType extends SpanType> {
  readonly id: string
  readonly traceId: string
  readonly type: TType
  readonly name: string

  /** Is an internal span? (spans internal to the operation of mastra) */
  isInternal: boolean

  /** Parent span reference (undefined for root spans) */
  parent?: AnySpan

  /** Pointer to the ObservabilityInstance instance */
  observabilityInstance: ObservabilityInstance

  attributes?: SpanTypeMap[TType]
  metadata?: Record<string, any>
  input?: any
  output?: any
  errorInfo?: any

  /** Tags for categorizing traces (only present on root spans) */
  tags?: string[]

  /** End the span */
  end(options?: EndSpanOptions<TType>): void

  /** Record an error for the span, optionally end the span as well */
  error(options: ErrorSpanOptions<TType>): void

  /** Update span attributes */
  update(options: UpdateSpanOptions<TType>): void

  /** Create child span - can be any span type independent of parent */
  createChildSpan<TChildType extends SpanType>(
    options: ChildSpanOptions<TChildType>,
  ): Span<TChildType>

  /** Create event span - can be any span type independent of parent */
  createEventSpan<TChildType extends SpanType>(
    options: ChildEventOptions<TChildType>,
  ): Span<TChildType>

  /** Returns TRUE if the span is the root span of a trace */
  get isRootSpan(): boolean

  /** Returns TRUE if the span is a valid span (not a NO-OP Span) */
  get isValid(): boolean
}
```

### `ObservabilityExporter`

Interface des exporters d’observabilité.

```typescript
interface ObservabilityExporter {
  /** Exporter name */
  name: string

  /** Initialize exporter with tracing configuration and/or access to Mastra */
  init?(options: InitExporterOptions): void

  /** Handle tracing events */
  onTracingEvent?(event: TracingEvent): void | Promise<void>

  /** Handle log events */
  onLogEvent?(event: LogEvent): void | Promise<void>

  /** Handle metric events */
  onMetricEvent?(event: MetricEvent): void | Promise<void>

  /** Handle score events */
  onScoreEvent?(event: ScoreEvent): void | Promise<void>

  /** Handle feedback events */
  onFeedbackEvent?(event: FeedbackEvent): void | Promise<void>

  /** Handle exporter pipeline droppedEvent */
  onDroppedEvent?(event: ObservabilityDropEvent): void | Promise<void>

  /** Export tracing events */
  exportTracingEvent(event: TracingEvent): Promise<void>

  /**
   * @deprecated Implement `onScoreEvent` instead. Eval scores now flow through the
   * unified observability bus as `ScoreEvent`s. This method is preserved on the
   * interface for backwards compatibility with existing exporters; new exporters
   * should not implement it.
   */
  addScoreToTrace?({
    traceId,
    spanId,
    score,
    reason,
    scorerName,
    metadata,
  }: {
    traceId: string
    spanId?: string
    score: number
    reason?: string
    scorerName: string
    metadata?: Record<string, any>
  }): Promise<void>

  /** Force flush any buffered spans without shutting down */
  flush(): Promise<void>

  /** Shutdown exporter */
  shutdown(): Promise<void>
}
```

Les charges utiles des callbacks d’événements utilisent les enveloppes du bus d’événements d’observabilité : `TracingEvent` transporte les événements du cycle de vie des spans avec `exportedSpan`, `LogEvent` encapsule `ExportedLog` dans `log`, `MetricEvent` encapsule `ExportedMetric` dans `metric`, `ScoreEvent` encapsule `ExportedScore` dans `score` et `FeedbackEvent` encapsule `ExportedFeedback` dans `feedback`. Pour connaître le comportement de l’exporter de la plateforme Mastra avec ces callbacks, consultez [MastraPlatformExporter](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/mastra-platform-exporter).

Comme `LogEvent`, `MetricEvent` et `FeedbackEvent`, `ScoreEvent` est une enveloppe du bus d’observabilité qui encapsule une charge utile délimitée. Pour les scores, cette charge utile est `ExportedScore`.

### `ScoreEvent`

Les événements de score sont envoyés aux exporters via `onScoreEvent`. L’événement est une petite enveloppe contenant le type de signal et la charge utile du score :

```typescript
interface ScoreEvent {
  type: 'score'
  score: ExportedScore
}
```

### `ExportedScore`

`ExportedScore` est la charge utile délimitée que les exporters reçoivent dans `ScoreEvent.score`. Elle contient l’identité du score, la trace ou le span cible servant de point d’ancrage, les informations sur le scorer, la valeur, une explication facultative et les métadonnées de corrélation.

```typescript
interface ExportedScore {
  scoreId: string
  timestamp: Date
  traceId?: string
  spanId?: string
  scorerId: string
  scorerName?: string
  scorerVersion?: string
  source?: string
  scoreSource?: string
  score: number
  reason?: string
  experimentId?: string
  scoreTraceId?: string
  targetEntityType?: EntityType
  correlationContext?: CorrelationContext
  metadata?: Record<string, unknown>
}
```

`traceId` et `spanId` identifient la trace ou le span évalué. `scoreTraceId` identifie la trace de l’exécution du scoring elle-même lorsque ce scorer a été tracé. Pour les nouveaux exporters, préférez `scoreSource` au champ obsolète `source`, et préférez `correlationContext.experimentId` au champ de premier niveau obsolète `experimentId`.

`EntityType` est l’énumération des entités d’observabilité de Mastra. Les valeurs actuelles incluent `agent`, `scorer`, `rag_ingestion`, `trajectory`, `input_processor`, `input_step_processor`, `output_processor`, `output_step_processor`, `workflow_step`, `tool`, `workflow_run` et `memory`.

`CorrelationContext` est l’instantané du contexte partagé attaché aux signaux d’observabilité. Il peut contenir des champs de hiérarchie d’entités, des identifiants d’utilisateur ou d’organisation, des informations sur l’exécution, la session, le thread, la requête, l’environnement, la source, le nom du service, l’expérimentation et les tags. Pour la cible évaluée, préférez les champs de premier niveau `traceId` et `spanId` de `ExportedScore`.

### `ObservabilityDropEvent`

Événement structuré émis lorsque le pipeline de l’exporter abandonne des événements d’observabilité.

```typescript
type ObservabilityDropSignal = 'tracing' | 'log' | 'metric' | 'score' | 'feedback'

type ObservabilityDropReason = 'unsupported-storage' | 'retry-exhausted'

interface ObservabilityDropEvent {
  type: 'drop'
  signal: ObservabilityDropSignal
  reason: ObservabilityDropReason
  count: number
  timestamp: Date
  exporterName: string
  storageName?: string
  error?: {
    id?: string
    domain?: string
    message: string
  }
}
```

Utilisez `onDroppedEvent` sur un exporter ou un bridge personnalisé pour transmettre ces événements à des systèmes externes de métriques ou d’alerte.

### `SpanOutputProcessor`

Interface des processeurs de sortie de spans.

```typescript
interface SpanOutputProcessor {
  /** Processor name */
  name: string

  /** Process span before export */
  process(span?: AnySpan): AnySpan | undefined

  /** Shutdown processor */
  shutdown(): Promise<void>
}
```

## Types de spans

### `SpanType`

Types de spans propres à l’IA avec leurs métadonnées associées.

```typescript
enum SpanType {
  /** Agent run - root span for agent processes */
  AGENT_RUN = 'agent_run',

  /** Generic span for custom operations */
  GENERIC = 'generic',

  /** Model generation with model calls, token usage, prompts, completions */
  MODEL_GENERATION = 'model_generation',

  /** Single model execution step within a generation (one API call) */
  MODEL_STEP = 'model_step',

  /** Individual model streaming chunk/event */
  MODEL_CHUNK = 'model_chunk',

  /** MCP (Model Context Protocol) tool execution */
  MCP_TOOL_CALL = 'mcp_tool_call',

  /** Input or Output Processor execution */
  PROCESSOR_RUN = 'processor_run',

  /** Function/tool execution with inputs, outputs, errors */
  TOOL_CALL = 'tool_call',

  /**
   * Client-side tool execution marker. The server creates this span
   * when the model emits a client tool call, injects its W3C carrier
   * into the outgoing tool-call chunk, then ends the span once tool
   * args are available. Child spans/logs from the client SDK flow back
   * as OTLP/JSON via the ClientObservabilityProxy interface in
   * @mastra/observability and parent themselves under this span.
   * See the "Client tools" section in the @mastra/client-js reference
   * for the full flow.
   */
  CLIENT_TOOL_CALL = 'client_tool_call',

  /**
   * Provider-executed (server-side) tool span. Reconstructed from
   * tool-call and tool-result stream chunks for tools the model
   * provider executes (e.g. Anthropic code execution, server-side
   * web search). Created on the tool-result chunk under the model
   * step that delivered it, with the start time backdated to the
   * tool-call chunk.
   */
  PROVIDER_TOOL_CALL = 'provider_tool_call',

  /** Workflow run - root span for workflow processes */
  WORKFLOW_RUN = 'workflow_run',

  /** Workflow step execution with step status, data flow */
  WORKFLOW_STEP = 'workflow_step',

  /** Workflow conditional execution with condition evaluation */
  WORKFLOW_CONDITIONAL = 'workflow_conditional',

  /** Individual condition evaluation within conditional */
  WORKFLOW_CONDITIONAL_EVAL = 'workflow_conditional_eval',

  /** Workflow parallel execution */
  WORKFLOW_PARALLEL = 'workflow_parallel',

  /** Workflow loop execution */
  WORKFLOW_LOOP = 'workflow_loop',

  /** Workflow sleep operation */
  WORKFLOW_SLEEP = 'workflow_sleep',

  /** Workflow wait for event operation */
  WORKFLOW_WAIT_EVENT = 'workflow_wait_event',
}
```

### `AnySpan`

Type union destiné aux cas qui doivent gérer n’importe quel span.

```typescript
type AnySpan = Span<keyof SpanTypeMap>
```

## Attributs des spans

### `AgentRunAttributes`

Attributs d’une exécution d’Agent.

```typescript
interface AgentRunAttributes {
  /** Agent identifier */
  agentId: string

  /** Agent Instructions */
  instructions?: string

  /** Agent Prompt */
  prompt?: string

  /** Available tools for this execution */
  availableTools?: string[]

  /** Maximum steps allowed */
  maxSteps?: number
}
```

### `ModelGenerationAttributes`

Attributs d’une génération de modèle.

```typescript
interface ModelGenerationAttributes {
  /** Model name (e.g., 'gpt-5.4', 'claude-opus-4-6') */
  model?: string

  /** Model provider (e.g., 'openai', 'anthropic') */
  provider?: string

  /**
   * Definitions of the tools made available to the model for this generation
   * (name, description, and JSON-schema parameters), captured once per
   * generation. Per-step tool names live on MODEL_INFERENCE spans as
   * `availableTools`.
   */
  tools?: ModelToolDefinition[]

  /** Type of result/output this model call produced */
  resultType?: 'tool_selection' | 'response_generation' | 'reasoning' | 'planning'

  /** Token usage statistics */
  usage?: {
    promptTokens?: number
    completionTokens?: number
    totalTokens?: number
    promptCacheHitTokens?: number
    promptCacheMissTokens?: number
  }

  /** Model parameters */
  parameters?: {
    maxOutputTokens?: number
    temperature?: number
    topP?: number
    topK?: number
    presencePenalty?: number
    frequencyPenalty?: number
    stopSequences?: string[]
    seed?: number
    maxRetries?: number
  }

  /** Whether this was a streaming response */
  streaming?: boolean

  /** Reason the generation finished */
  finishReason?: string
}
```

### `ModelToolDefinition`

Définition sérialisée d’un outil mis à la disposition du modèle, attachée aux spans `MODEL_GENERATION` afin que les exporters d’observabilité puissent exposer les schémas des outils.

```typescript
interface ModelToolDefinition {
  /** Tool type: 'function' for standard tools, or the provider tool type (e.g. 'provider-defined') */
  type: string

  name: string

  description?: string

  /** JSON schema of the tool's input parameters (function tools) */
  parameters?: Record<string, unknown>

  /** Provider tool id (e.g. 'anthropic.web_search_20250305') for provider-defined tools */
  id?: string
}
```

### `ModelStepAttributes`

Attributs d’une étape du modèle, pour une seule exécution du modèle au sein d’une génération.

```typescript
interface ModelStepAttributes {
  /** Index of this step in the generation (0, 1, 2, ...) */
  stepIndex?: number

  /** Token usage statistics */
  usage?: UsageStats

  /** Reason this step finished (stop, tool-calls, length, etc.) */
  finishReason?: string

  /** Should execution continue */
  isContinued?: boolean

  /** Result warnings */
  warnings?: Record<string, any>
}
```

### `ModelChunkAttributes`

Attributs d’un chunk de modèle, pour chaque chunk ou événement de streaming.

```typescript
interface ModelChunkAttributes {
  /** Type of chunk (text-delta, reasoning-delta, tool-call, etc.) */
  chunkType?: string

  /** Sequence number of this chunk in the stream */
  sequenceNumber?: number
}
```

### `ToolCallAttributes`

Attributs d’un appel d’outil.

```typescript
interface ToolCallAttributes {
  toolId?: string
  toolType?: string
  toolDescription?: string
  toolCallId?: string
  success?: boolean
}
```

### MCPToolCallAttributes

Attributs d’un appel d’outil MCP.

```typescript
interface MCPToolCallAttributes {
  /** Id of the MCP tool/function */
  toolId: string

  /** MCP server identifier */
  mcpServer: string

  /** MCP server version */
  serverVersion?: string

  /** Tool description */
  toolDescription?: string

  toolCallId?: string

  /** Whether tool execution was successful */
  success?: boolean
}
```

### `ProcessorRunAttributes`

Attributs d’un Processor.

```typescript
interface ProcessorRunAttributes {
  /** Name of the Processor */
  processorName: string

  /** Processor type (input or output) */
  processorType: 'input' | 'output'

  /** Processor index in the agent */
  processorIndex?: number
}
```

### `WorkflowRunAttributes`

Attributs d’une exécution de Workflow.

```typescript
interface WorkflowRunAttributes {
  /** Workflow identifier */
  workflowId: string

  /** Workflow status */
  status?: WorkflowRunStatus
}
```

### `WorkflowStepAttributes`

Attributs d’une étape de Workflow.

```typescript
interface WorkflowStepAttributes {
  /** Step identifier */
  stepId: string

  /** Step status */
  status?: WorkflowStepStatus
}
```

## Types d’options

### `StartSpanOptions`

Options permettant de démarrer de nouveaux spans.

```typescript
interface StartSpanOptions<TType extends SpanType> {
  /** Span type */
  type: TType

  /** Span name */
  name: string

  /** Span attributes */
  attributes?: SpanTypeMap[TType]

  /** Span metadata */
  metadata?: Record<string, any>

  /** Input data */
  input?: any

  /** Parent span */
  parent?: AnySpan

  /** Policy-level tracing configuration */
  tracingPolicy?: TracingPolicy

  /** Options passed when using a custom sampler strategy */
  customSamplerOptions?: CustomSamplerOptions
}
```

### `UpdateSpanOptions`

Options permettant de mettre à jour des spans.

```typescript
interface UpdateSpanOptions<TType extends SpanType> {
  /** Span attributes */
  attributes?: Partial<SpanTypeMap[TType]>

  /** Span metadata */
  metadata?: Record<string, any>

  /** Input data */
  input?: any

  /** Output data */
  output?: any
}
```

### `EndSpanOptions`

Options permettant de terminer des spans.

```typescript
interface EndSpanOptions<TType extends SpanType> {
  /** Output data */
  output?: any

  /** Span metadata */
  metadata?: Record<string, any>

  /** Span attributes */
  attributes?: Partial<SpanTypeMap[TType]>
}
```

### `ErrorSpanOptions`

Options permettant d’enregistrer les erreurs des spans.

```typescript
interface ErrorSpanOptions<TType extends SpanType> {
  /** The error associated with the issue */
  error: Error

  /** End the span when true */
  endSpan?: boolean

  /** Span metadata */
  metadata?: Record<string, any>

  /** Span attributes */
  attributes?: Partial<SpanTypeMap[TType]>
}
```

## Types de contexte

### `TracingContext`

Contexte de Tracing propagé pendant l’exécution d’un Workflow et d’un Agent.

```typescript
interface TracingContext {
  /** Current span for creating child spans and adding metadata */
  currentSpan?: AnySpan
}
```

### `TracingProperties`

Propriétés renvoyées à l’utilisateur pour manipuler les traces depuis l’extérieur.

```typescript
type TracingProperties = {
  /** Trace ID used on the execution (if the execution was traced) */
  traceId?: string
}
```

### `TracingOptions`

Options transmises lors du démarrage d’une nouvelle exécution d’Agent ou de Workflow.

```typescript
interface TracingOptions {
  /** Metadata to add to the root trace span */
  metadata?: Record<string, any>

  /**
   * Additional RequestContext keys to extract as metadata for this trace.
   * These keys are added to the requestContextKeys config.
   * Supports dot notation for nested values (e.g., 'user.id', 'session.data.experimentId').
   */
  requestContextKeys?: string[]

  /**
   * Trace ID to use for this execution (1-32 hexadecimal characters).
   * If provided, this trace will be part of the specified trace rather than starting a new one.
   */
  traceId?: string

  /**
   * Parent span ID to use for this execution (1-16 hexadecimal characters).
   * If provided, the root span will be created as a child of this span.
   */
  parentSpanId?: string

  /**
   * Tags to apply to this trace.
   * Tags are string labels that can be used to categorize and filter traces
   * Note: Tags are only applied to the root span of a trace.
   */
  tags?: string[]

  /**
   * When true, input data will be hidden from all spans in this trace.
   * Useful for protecting sensitive data from being logged.
   */
  hideInput?: boolean

  /**
   * When true, output data will be hidden from all spans in this trace.
   * Useful for protecting sensitive data from being logged.
   */
  hideOutput?: boolean
}
```

### `TracingPolicy`

Configuration du tracing au niveau de la stratégie, appliquée lors de la création d’un Workflow ou d’un Agent.

```typescript
interface TracingPolicy {
  /**
   * Bitwise options to set different types of spans as Internal in
   * a workflow or agent execution. Internal spans are hidden by
   * default in exported traces.
   */
  internal?: InternalSpans
}
```

## Types de configuration

### `ObservabilityInstanceConfig`

Configuration d’une instance d’observabilité unique.

```typescript
interface ObservabilityInstanceConfig {
  /** Unique identifier for this config in the observability registry */
  name: string

  /** Service name for observability */
  serviceName: string

  /** Sampling strategy - controls whether tracing is collected (defaults to ALWAYS) */
  sampling?: SamplingStrategy

  /** Custom exporters */
  exporters?: ObservabilityExporter[]

  /** Custom span output processors */
  spanOutputProcessors?: SpanOutputProcessor[]

  /** Set to true if you want to see spans internal to the operation of mastra */
  includeInternalSpans?: boolean

  /** RequestContext keys to automatically extract as metadata for all spans */
  requestContextKeys?: string[]
}
```

### `ObservabilityRegistryConfig`

Configuration complète du registre d’observabilité.

```typescript
interface ObservabilityRegistryConfig {
  /** Enables default exporters, with sampling: always, and sensitive data filtering */
  default?: {
    enabled?: boolean
  }

  /** Map of tracing instance names to their configurations or pre-instantiated instances */
  configs?: Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>

  /** Optional selector function to choose which tracing instance to use */
  configSelector?: ConfigSelector
}
```

## Types d’échantillonnage

### `SamplingStrategy`

Configuration de la stratégie d’échantillonnage.

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

### `CustomSamplerOptions`

Options transmises lors de l’utilisation d’une stratégie d’échantillonnage personnalisée.

```typescript
interface CustomSamplerOptions {
  requestContext?: RequestContext
  metadata?: Record<string, any>
}
```

## Types de sélecteur de configuration

### `ConfigSelector`

Fonction permettant de sélectionner l’instance d’observabilité à utiliser pour un span.

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

### `ConfigSelectorOptions`

Options transmises lors de l’utilisation d’un sélecteur de configuration de tracing personnalisé.

```typescript
interface ConfigSelectorOptions {
  /** Request Context */
  requestContext?: RequestContext
}
```

## Spans internes

### `InternalSpans`

Options bit à bit permettant de définir différents types de spans comme internes lors de l’exécution d’un Workflow ou d’un Agent.

```typescript
enum InternalSpans {
  /** No spans are marked internal */
  NONE = 0,

  /** Workflow spans are marked internal */
  WORKFLOW = 1 << 0,

  /** Agent spans are marked internal */
  AGENT = 1 << 1,

  /** Tool spans are marked internal */
  TOOL = 1 << 2,

  /** Model spans are marked internal */
  MODEL = 1 << 3,

  /** All spans are marked internal */
  ALL = (1 << 4) - 1,
}
```

## Voir aussi

### Documentation

- [Présentation du Tracing](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview) : guide complet du Tracing
- [Créer des spans enfants](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview) : utiliser les hiérarchies de spans
- [Ajouter des métadonnées personnalisées](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview) : enrichir les traces

### Référence

- [Configuration](https://mastra.zisheng.pro/fr/reference/observability/tracing/configuration) : registre et configuration
- [Classes de Tracing](https://mastra.zisheng.pro/fr/reference/observability/tracing/instances) : implémentations principales
- [Référence des spans](https://mastra.zisheng.pro/fr/reference/observability/tracing/spans) : méthodes du cycle de vie des spans