Spans

BaseSpan

Base interface for all span types.

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?: SpanInput<TType>

  /** Output generated at the end of the span */
  output?: SpanOutput<TType>

  /** 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? (point-in-time: endTime equals startTime) */
  isEvent: boolean
}

Span

Span interface, used internally for tracing. Extends BaseSpan with lifecycle methods and properties.

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
}

Properties

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

Methods

end

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

Ends the span and triggers export to configured exporters. Sets the endTime and optionally updates output, metadata, and attributes.

error

error(options: ErrorSpanOptions<TType>): void

Records an error on the span. Sets the errorInfo field and can optionally end the span. When the error is an AI SDK APICallError (or wraps one as cause), errorInfo.details also carries the HTTP statusCode, request url, isRetryable flag and provider responseBody.

update

update(options: UpdateSpanOptions<TType>): void

Updates span data while it's still active. Can modify input, output, metadata, and attributes.

createChildSpan

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

Creates a child span under this span. Child spans track sub-operations and inherit the trace context.

createEventSpan

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

Creates an event span under this span. Event spans represent point-in-time occurrences with no duration. They're emitted as soon as they're created, with isEvent: true and an endTime equal to their startTime, so stored and exported records have endedAt equal to startedAt.

ExportedSpan

Exported Span interface, used for tracing exporters. A lightweight version of Span without methods or circular references.

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
}

Span lifecycle events

Events emitted during the span lifecycle.

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 }

Exporters receive these events to process and send trace data to observability platforms.

Union types

AnySpan

type AnySpan = Span<keyof SpanTypeMap>

Union type for cases that need to handle any span type.

AnyExportedSpan

type AnyExportedSpan = ExportedSpan<keyof SpanTypeMap>

Union type for cases that need to handle any exported span type.

NO-OP spans

When tracing is disabled (sampling returns false), NO-OP spans are returned:

NoOpSpan

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

A span that performs no operations. All methods are no-ops:

• id returns 'no-op'
• traceId returns 'no-op-trace'
• isValid returns false
• end(), error(), update() do nothing
• createChildSpan() returns another NO-OP span

See also

Documentation

• Tracing Overview: Concepts and usage
• Creating Child Spans: Practical examples
• Retrieving Trace IDs: Using trace IDs

Reference

• Tracing Classes: Core tracing classes
• Interfaces: Complete type reference
• Configuration: Configuration options