Spans

BaseSpan

Interface de base de tous les types de spans.

interface BaseSpan<TType extends SpanType> {
  /** Unique span identifier */
  id: string

  /** OpenTelemetry-compatible trace ID (32 hex chars) */
  traceId: string

  /** Name of the span */
  name: string

  /** Type of the span */
  type: TType

  /** When span started */
  startTime: Date

  /** When span ended */
  endTime?: Date

  /** Type-specific attributes */
  attributes?: SpanTypeMap[TType]

  /** User-defined metadata */
  metadata?: Record<string, any>

  /** Input passed at the start of the span */
  input?: any

  /** Output generated at the end of the span */
  output?: any

  /** Error information if span failed */
  errorInfo?: {
    message: string
    id?: string
    domain?: string
    category?: string
    details?: Record<string, any>
  }

  /** Snapshot of the RequestContext */
  requestContext?: Record<string, any>
  /** Is an event span? (occurs at startTime, has no endTime) */
  isEvent: boolean
}

Span

Interface Span utilisée en interne pour le Tracing. Étend BaseSpan avec des méthodes et des propriétés de cycle de vie.

interface Span<TType extends SpanType> extends BaseSpan<TType> {
  /** 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
}

Propriétés

/** 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

/** Get the closest parent spanId that isn't an internal span */
getParentSpanId(includeInternalSpans?: boolean): string | undefined

/** Returns a lightweight span ready for export */
exportSpan(includeInternalSpans?: boolean): ExportedSpan<TType> | undefined

Méthodes

end

end(options?: EndSpanOptions<TType>): void

Termine le span et déclenche son exportation vers les Exporters configurés. Définit endTime et met éventuellement à jour output, metadata et attributes.

error

error(options: ErrorSpanOptions<TType>): void

Enregistre une erreur sur le span. Définit le champ errorInfo et peut éventuellement terminer le span.

update

update(options: UpdateSpanOptions<TType>): void

Met à jour les données du span tant qu'il est actif. Peut modifier input, output, metadata et attributes.

createChildSpan

createChildSpan<TChildType extends SpanType>(
  options: ChildSpanOptions<TChildType>
): Span<TChildType>

Crée un span enfant sous ce span. Les spans enfants suivent les sous-opérations et héritent du contexte de la Trace.

createEventSpan

createEventSpan<TChildType extends SpanType>(
  options: ChildEventOptions<TChildType>
): Span<TChildType>

Crée un span d'événement sous ce span. Les spans d'événement représentent des occurrences ponctuelles sans durée.

ExportedSpan

Interface Span exportée, utilisée par les Exporters de Tracing. Version légère de Span, sans méthodes ni références circulaires.

interface ExportedSpan<TType extends SpanType> extends BaseSpan<TType> {
  /** Parent span id reference (undefined for root spans) */
  parentSpanId?: string

  /** TRUE if the span is the root span of a trace */
  isRootSpan: boolean
}

Événements du cycle de vie des spans

Événements émis pendant le cycle de vie du span.

TracingEventType

enum TracingEventType {
  /** Emitted when a span is created and started */
  SPAN_STARTED = 'span_started',

  /** Emitted when a span is updated via update() */
  SPAN_UPDATED = 'span_updated',

  /** Emitted when a span is ended via end() or error() */
  SPAN_ENDED = 'span_ended',
}

TracingEvent

type TracingEvent =
  | { type: 'span_started'; exportedSpan: AnyExportedSpan }
  | { type: 'span_updated'; exportedSpan: AnyExportedSpan }
  | { type: 'span_ended'; exportedSpan: AnyExportedSpan }

Les Exporters reçoivent ces événements afin de traiter et d'envoyer les données de Trace aux plateformes d'Observability.

Types union

AnySpan

type AnySpan = Span<keyof SpanTypeMap>

Type union destiné aux cas où tout type de span doit être traité.

AnyExportedSpan

type AnyExportedSpan = ExportedSpan<keyof SpanTypeMap>

Type union destiné aux cas où tout type de span exporté doit être traité.

Spans NO-OP

Lorsque le Tracing est désactivé (l'échantillonnage renvoie false), des spans NO-OP sont renvoyés :

NoOpSpan

class NoOpSpan<TType extends SpanType> extends BaseSpan<TType>

Span qui n'effectue aucune opération. Toutes ses méthodes ne font rien :

• id renvoie 'no-op'
• traceId renvoie 'no-op-trace'
• isValid renvoie false
• end(), error(), update() ne font rien
• createChildSpan() renvoie un autre span NO-OP

Voir aussi

Documentation

• Présentation du Tracing : concepts et utilisation
• Création de spans enfants : exemples pratiques
• Récupération des identifiants de Trace : utilisation des identifiants de Trace

Référence

• Classes de Tracing : classes principales de Tracing
• Interfaces : référence complète des types
• Configuration : options de configuration