> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Span

## `BaseSpan`

所有 Span 类型的基础接口。

```typescript
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。

```typescript
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
}
```

### 属性

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

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

结束 Span 并触发向已配置 Exporter 的导出。设置 `endTime`，并可选择更新 `output`、`metadata` 和 `attributes`。

#### error

```typescript
error(options: ErrorSpanOptions<TType>): void
```

在 Span 上记录错误。设置 `errorInfo` 字段，并可选择结束该 Span。

#### update

```typescript
update(options: UpdateSpanOptions<TType>): void
```

在 Span 仍处于活动状态时更新其数据。可以修改 `input`、`output`、`metadata` 和 `attributes`。

#### `createChildSpan`

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

在此 Span 下创建子 Span。子 Span 会追踪子操作并继承 Trace 上下文。

#### `createEventSpan`

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

在此 Span 下创建事件 Span。事件 Span 表示在某个时间点发生、没有持续时间的事件。

## `ExportedSpan`

导出的 Span 接口，供 Tracing Exporter 使用。它是 Span 的轻量版本，不含方法或循环引用。

```typescript
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`

```typescript
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`

```typescript
type TracingEvent =
  | { type: 'span_started'; exportedSpan: AnyExportedSpan }
  | { type: 'span_updated'; exportedSpan: AnyExportedSpan }
  | { type: 'span_ended'; exportedSpan: AnyExportedSpan }
```

Exporter 接收这些事件，以处理 Trace 数据并将其发送到可观测性平台。

## 联合类型

### `AnySpan`

```typescript
type AnySpan = Span<keyof SpanTypeMap>
```

用于需要处理任意 Span 类型的场景的联合类型。

### `AnyExportedSpan`

```typescript
type AnyExportedSpan = ExportedSpan<keyof SpanTypeMap>
```

用于需要处理任意已导出 Span 类型的场景的联合类型。

## NO-OP Span

禁用 Tracing（采样返回 false）时，会返回 NO-OP Span：

### `NoOpSpan`

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

不执行任何操作的 Span。所有方法均为空操作：

- `id` 返回 `'no-op'`
- `traceId` 返回 `'no-op-trace'`
- `isValid` 返回 `false`
- `end()`、`error()`、`update()` 不执行任何操作
- `createChildSpan()` 返回另一个 NO-OP Span

## 另请参阅

### 文档

- [Tracing 概览](https://mastra.zisheng.pro/docs/observability/tracing/overview)：概念和用法
- [创建子 Span](https://mastra.zisheng.pro/docs/observability/tracing/overview)：实用示例
- [检索 Trace ID](https://mastra.zisheng.pro/docs/observability/tracing/overview)：使用 Trace ID

### 参考

- [Tracing 类](https://mastra.zisheng.pro/reference/observability/tracing/instances)：核心 Tracing 类
- [接口](https://mastra.zisheng.pro/reference/observability/tracing/interfaces)：完整类型参考
- [配置](https://mastra.zisheng.pro/reference/observability/tracing/configuration)：配置选项