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

# Spans

## `BaseSpan`

Interface de base de tous les types de spans.

```typescript
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.

```typescript
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

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

```typescript
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

```typescript
error(options: ErrorSpanOptions<TType>): void
```

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

#### update

```typescript
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`

```typescript
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`

```typescript
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.

```typescript
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`

```typescript
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`

```typescript
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`

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

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

### `AnyExportedSpan`

```typescript
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`

```typescript
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](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview) : concepts et utilisation
- [Création de spans enfants](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview) : exemples pratiques
- [Récupération des identifiants de Trace](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview) : utilisation des identifiants de Trace

### Référence

- [Classes de Tracing](https://mastra.zisheng.pro/fr/reference/observability/tracing/instances) : classes principales de Tracing
- [Interfaces](https://mastra.zisheng.pro/fr/reference/observability/tracing/interfaces) : référence complète des types
- [Configuration](https://mastra.zisheng.pro/fr/reference/observability/tracing/configuration) : options de configuration