Span

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;
}

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;
}

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

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

error(options: ErrorSpanOptions<TType>): void

update(options: UpdateSpanOptions<TType>): void

createChildSpan<TChildType extends AISpanType>(
  options: ChildSpanOptions<TChildType>
): AISpan<TChildType>

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

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;
}

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',
}

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

type AnyAISpan = AISpan<keyof AISpanTypeMap>;

type AnyExportedAISpan = ExportedAISpan<keyof AISpanTypeMap>;