ContextQMD
Back to Mastra

Reference: Spans | Observability

docs/src/content/en/reference/observability/tracing/spans.mdx

2025-12-188.4 KB
Original Source

import PropertiesTable from "@site/src/components/PropertiesTable";

Spans

BaseSpan

Base interface for all span types.

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

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

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
}

Properties

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

Methods

end

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

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

<PropertiesTable props={[ { name: 'output', type: 'any', description: 'Final output data from the operation', required: false, }, { name: 'metadata', type: 'Record<string, any>', description: 'Additional metadata to merge', required: false, }, { name: 'attributes', type: 'Partial<SpanTypeMap[TType]>', description: 'Type-specific attributes to update', required: false, }, ]} />

error

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

Records an error on the span. Sets the errorInfo field and can optionally end the span.

<PropertiesTable props={[ { name: 'error', type: 'Error', description: 'The error that occurred', required: true, }, { name: 'endSpan', type: 'boolean', description: 'Whether to end the span after recording the error', required: false, }, { name: 'metadata', type: 'Record<string, any>', description: 'Additional error context metadata', required: false, }, { name: 'attributes', type: 'Partial<SpanTypeMap[TType]>', description: 'Type-specific attributes to update', required: false, }, ]} />

update

typescript
update(options: UpdateSpanOptions<TType>): void

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

<PropertiesTable props={[ { name: 'input', type: 'any', description: 'Update or set input data', required: false, }, { name: 'output', type: 'any', description: 'Update or set output data', required: false, }, { name: 'metadata', type: 'Record<string, any>', description: 'Metadata to merge with existing', required: false, }, { name: 'attributes', type: 'Partial<SpanTypeMap[TType]>', description: 'Type-specific attributes to update', required: false, }, ]} />

createChildSpan

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

<PropertiesTable props={[ { name: 'type', type: 'TChildType', description: 'Type of the child span', required: true, }, { name: 'name', type: 'string', description: 'Name of the child span', required: true, }, { name: 'attributes', type: 'SpanTypeMap[TChildType]', description: 'Type-specific attributes', required: false, }, { name: 'metadata', type: 'Record<string, any>', description: 'Initial metadata', required: false, }, { name: 'input', type: 'any', description: 'Initial input data', required: false, }, ]} />

createEventSpan

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

<PropertiesTable props={[ { name: 'type', type: 'TChildType', description: 'Type of the event span', required: true, }, { name: 'name', type: 'string', description: 'Name of the event', required: true, }, { name: 'attributes', type: 'SpanTypeMap[TChildType]', description: 'Type-specific attributes', required: false, }, { name: 'metadata', type: 'Record<string, any>', description: 'Event metadata', required: false, }, { name: 'input', type: 'any', description: 'Event input data', required: false, }, { name: 'output', type: 'any', description: 'Event output data', required: false, }, ]} />

ExportedSpan

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

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
}

Span lifecycle events

Events emitted during the span lifecycle.

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 }

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

Union types

AnySpan

typescript
type AnySpan = Span<keyof SpanTypeMap>

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

AnyExportedSpan

typescript
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

typescript
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

Reference