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

tracing で内部的に使用される Span インターフェースです。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 への export を開始します。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 の下に子 span を作成します。子 span はサブ操作を追跡し、Trace コンテキストを継承します。

createEventSpan

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

この span の下にイベント span を作成します。イベント span は、継続時間のない特定時点の事象を表します。

ExportedSpan

tracing exporter で使用される、export 済み Span のインターフェースです。メソッドや循環参照を持たない軽量版の 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 型

AnySpan

type AnySpan = Span<keyof SpanTypeMap>

任意の span 型を処理する必要がある場合の Union 型です。

AnyExportedSpan

type AnyExportedSpan = ExportedSpan<keyof SpanTypeMap>

任意の export 済み span 型を処理する必要がある場合の Union 型です。

NO-OP span

tracing が無効な場合（sampling が 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 の概要：概念と使用方法
• 子 span の作成：実践的な例
• Trace ID の取得：Trace ID の使用方法

リファレンス

• Tracing クラス：tracing の主要クラス
• インターフェース：完全な型リファレンス
• 設定：設定オプション