Spans

BaseSpan

所有 span 類型的基礎介面。

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 介面，在內部用於 Tracing。它以生命週期方法及屬性擴充 BaseSpan。

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
}

屬性

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

方法

end

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

結束 span，並觸發向已設定的 exporter 匯出。此方法會設定 endTime，亦可選擇更新 output、metadata 及 attributes。

error

error(options: ErrorSpanOptions<TType>): void

在 span 上記錄錯誤。設定 errorInfo 欄位，亦可選擇結束 span。

update

update(options: UpdateSpanOptions<TType>): void

在 span 仍處於活動狀態時更新其資料。可修改 input、output、metadata 及 attributes。

createChildSpan

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

在此 span 下建立 child span。Child span 會追蹤子操作並繼承 Trace 情境。

createEventSpan

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

在此 span 下建立 event span。Event span 代表在特定時間點發生、沒有持續時間的事件。

ExportedSpan

匯出的 Span 介面，用於 Tracing exporter。這是沒有方法或循環參照的輕量版 Span。

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 生命週期事件

在 span 生命週期期間發出的事件。

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 }

Exporter 會接收這些事件，以處理 Trace 資料並將其傳送至 observability 平台。

Union type

AnySpan

type AnySpan = Span<keyof SpanTypeMap>

適用於需要處理任何 span 類型的 union type。

AnyExportedSpan

type AnyExportedSpan = ExportedSpan<keyof SpanTypeMap>

適用於需要處理任何已匯出 span 類型的 union type。

NO-OP span

停用 Tracing 時（取樣傳回 false），系統會傳回 NO-OP span：

NoOpSpan

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

不執行任何操作的 span。所有方法均為 no-op：

• id 傳回 'no-op'
• traceId 傳回 'no-op-trace'
• isValid 傳回 false
• end()、error()、update() 不執行任何操作
• createChildSpan() 傳回另一個 NO-OP span

另請參閱

文件

• Tracing 概覽：概念及用法
• 建立 Child Span：實際範例
• 取得 Trace ID：使用 Trace ID

參考

• Tracing 類別：核心 Tracing 類別
• 介面：完整類型參考
• 設定：設定選項