Skip to main content

Span

BaseSpan​

Base interface for all span types.

interface BaseSpan<TType extends AISpanType> {
  /** 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?: AISpanTypeMap[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>;
  };

  /** Is an event span? (occurs at startTime, has no endTime) */
  isEvent: boolean;
}

AISpan​

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

interface AISpan<TType extends AISpanType> extends BaseSpan<TType> {
  /** Is an internal span? (spans internal to the operation of mastra) */
  isInternal: boolean;

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

  /** Pointer to the AITracing instance */
  aiTracing: AITracing;
}

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): ExportedAISpan<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.

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 AISpanType>(
  options: ChildSpanOptions<TChildType>
): AISpan<TChildType>

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

createEventSpan​

createEventSpan<TChildType extends AISpanType>(
  options: ChildEventOptions<TChildType>
): AISpan<TChildType>

Creates an event span under this span. Event spans represent point-in-time occurrences with no duration.

ExportedAISpan​

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

interface ExportedAISpan<TType extends AISpanType> 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.

AITracingEventType​

enum AITracingEventType {
  /** 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",
}

AITracingEvent​

type AITracingEvent =
  | { type: "span_started"; exportedSpan: AnyExportedAISpan }
  | { type: "span_updated"; exportedSpan: AnyExportedAISpan }
  | { type: "span_ended"; exportedSpan: AnyExportedAISpan };

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

Union Types​

AnyAISpan​

type AnyAISpan = AISpan<keyof AISpanTypeMap>;

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

AnyExportedAISpan​

type AnyExportedAISpan = ExportedAISpan<keyof AISpanTypeMap>;

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

See Also​

Documentation​

Reference​

Examples​