跨度

🌐 Spans

BaseSpan

所有跨度类型的基础接口。

🌐 Base interface for all span types.

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

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

跨度

🌐 Span

Span 接口，用于内部追踪。通过生命周期方法和属性扩展了 BaseSpan。

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

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

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

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

结束跨度并触发导出到配置的导出器。设置 endTime，并可选择更新 output、metadata 和 attributes。

🌐 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

在跨度上记录一个错误。设置 errorInfo 字段，并可以选择性地结束该跨度。

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

update

update(options: UpdateSpanOptions<TType>): void

在跨度数据仍处于活动状态时进行更新。可以修改 input、output、metadata 和 attributes。

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

createChildSpan

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.

createEventSpan

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.

ExportedSpan

导出的 Span 接口，用于跟踪导出器。Span 的轻量版本，不包含方法或循环引用。

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

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

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

导出器接收这些事件以处理并将追踪数据发送到可观察性平台。

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

联合类型

🌐 Union Types

AnySpan

type AnySpan = Span<keyof SpanTypeMap>;

用于需要处理任何跨度类型的情况的联合类型。

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

AnyExportedSpan

type AnyExportedSpan = ExportedSpan<keyof SpanTypeMap>;

用于需要处理任何导出跨度类型的情况的联合类型。

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

无操作跨度

🌐 NO-OP Spans

当跟踪被禁用（采样返回 false）时，会返回 NO-OP span：

🌐 When tracing is disabled (sampling returns false), NO-OP spans are returned:

NoOpSpan

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

一个不执行任何操作的跨度。所有方法都是无操作的：

🌐 A span that performs no operations. All methods are no-ops:

• id 返回 'no-op'
• traceId 返回 'no-op-trace'
• isValid 返回 false
• end()、error()、update() 无任何作用
• createChildSpan() 返回另一个无操作跨度

另请参阅

🌐 See Also

文档

🌐 Documentation

• 跟踪概览 - 概念与使用
• 创建子跨度 - 实用示例
• 检索跟踪 ID - 使用跟踪 ID

参考

🌐 Reference

• 跟踪类 - 核心跟踪类
• 接口 - 完整类型参考
• 配置 - 配置选项