---
title: "Reference: Spans | Observability"
description: Span interfaces, methods, and lifecycle events
packages:
  - "@mastra/core"
---

import PropertiesTable from "@site/src/components/PropertiesTable";

# Spans

## BaseSpan

Base interface for all span types.

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

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

## Span

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

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

### Properties

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

### Methods

#### end

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

Ends the span and triggers export to configured exporters. Sets the `endTime` and optionally updates `output`, `metadata`, and `attributes`.

<PropertiesTable
  props={[
    {
      name: "output",
      type: "any",
      description: "Final output data from the operation",
      required: false,
    },
    {
      name: "metadata",
      type: "Record<string, any>",
      description: "Additional metadata to merge",
      required: false,
    },
    {
      name: "attributes",
      type: "Partial<SpanTypeMap[TType]>",
      description: "Type-specific attributes to update",
      required: false,
    },
  ]}
/>

#### error

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

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

<PropertiesTable
  props={[
    {
      name: "error",
      type: "Error",
      description: "The error that occurred",
      required: true,
    },
    {
      name: "endSpan",
      type: "boolean",
      description: "Whether to end the span after recording the error",
      required: false,
    },
    {
      name: "metadata",
      type: "Record<string, any>",
      description: "Additional error context metadata",
      required: false,
    },
    {
      name: "attributes",
      type: "Partial<SpanTypeMap[TType]>",
      description: "Type-specific attributes to update",
      required: false,
    },
  ]}
/>

#### update

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

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

<PropertiesTable
  props={[
    {
      name: "input",
      type: "any",
      description: "Update or set input data",
      required: false,
    },
    {
      name: "output",
      type: "any",
      description: "Update or set output data",
      required: false,
    },
    {
      name: "metadata",
      type: "Record<string, any>",
      description: "Metadata to merge with existing",
      required: false,
    },
    {
      name: "attributes",
      type: "Partial<SpanTypeMap[TType]>",
      description: "Type-specific attributes to update",
      required: false,
    },
  ]}
/>

#### createChildSpan

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

<PropertiesTable
  props={[
    {
      name: "type",
      type: "TChildType",
      description: "Type of the child span",
      required: true,
    },
    {
      name: "name",
      type: "string",
      description: "Name of the child span",
      required: true,
    },
    {
      name: "attributes",
      type: "SpanTypeMap[TChildType]",
      description: "Type-specific attributes",
      required: false,
    },
    {
      name: "metadata",
      type: "Record<string, any>",
      description: "Initial metadata",
      required: false,
    },
    {
      name: "input",
      type: "any",
      description: "Initial input data",
      required: false,
    },
  ]}
/>

#### createEventSpan

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

<PropertiesTable
  props={[
    {
      name: "type",
      type: "TChildType",
      description: "Type of the event span",
      required: true,
    },
    {
      name: "name",
      type: "string",
      description: "Name of the event",
      required: true,
    },
    {
      name: "attributes",
      type: "SpanTypeMap[TChildType]",
      description: "Type-specific attributes",
      required: false,
    },
    {
      name: "metadata",
      type: "Record<string, any>",
      description: "Event metadata",
      required: false,
    },
    {
      name: "input",
      type: "any",
      description: "Event input data",
      required: false,
    },
    {
      name: "output",
      type: "any",
      description: "Event output data",
      required: false,
    },
  ]}
/>

## ExportedSpan

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

```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 Lifecycle Events

Events emitted during the span lifecycle.

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

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

## Union Types

### AnySpan

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

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

### AnyExportedSpan

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

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

## NO-OP Spans

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

### NoOpSpan

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

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

- `id` returns `'no-op'`
- `traceId` returns `'no-op-trace'`
- `isValid` returns `false`
- `end()`, `error()`, `update()` do nothing
- `createChildSpan()` returns another NO-OP span

## See Also

### Documentation

- [Tracing Overview](/docs/v1/observability/tracing/overview) - Concepts and usage
- [Creating Child Spans](/docs/v1/observability/tracing/overview#creating-child-spans) - Practical examples
- [Retrieving Trace IDs](/docs/v1/observability/tracing/overview#retrieving-trace-ids) - Using trace IDs

### Reference

- [Tracing Classes](/reference/v1/observability/tracing/instances) - Core tracing classes
- [Interfaces](/reference/v1/observability/tracing/interfaces) - Complete type reference
- [Configuration](/reference/v1/observability/tracing/configuration) - Configuration options
