> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirador.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Span

> A timed, nestable unit of work within a trace

**Web Client SDK:**

```typescript theme={null}
import { Span } from '@miradorlabs/web-sdk';
```

**Node.js SDK:**

```typescript theme={null}
import { Span } from '@miradorlabs/nodejs-sdk';
```

<Note>
  You don't instantiate `Span` directly. Create one with [`trace.startSpan()`](/api-reference/trace#startspan) or the [`trace.span()`](/api-reference/trace#span) wrapper, and nest with `span.startSpan()`. See [Spans](/concepts/spans) for a conceptual overview.
</Note>

## Properties

### id

The span's W3C Trace Context id (16 lowercase hex characters). Available immediately.

```typescript theme={null}
readonly id: string
```

Also available as `getSpanId(): string`.

## Methods

### setAttribute()

Set a single span attribute. Set attributes at creation or synchronously afterwards — before the span first flushes.

```typescript theme={null}
setAttribute(key: string, value: string | number | boolean | object): Span
```

#### Parameters

| Parameter | Type                                    | Description                                    |
| --------- | --------------------------------------- | ---------------------------------------------- |
| `key`     | `string`                                | Attribute key                                  |
| `value`   | `string \| number \| boolean \| object` | Attribute value (objects are JSON stringified) |

#### Examples

```typescript theme={null}
span.setAttribute('amountIn', '1.5')
    .setAttribute('slippage', 0.5);
```

***

### setAttributes()

Set multiple span attributes at once.

```typescript theme={null}
setAttributes(attrs: Record<string, string | number | boolean | object>): Span
```

#### Examples

```typescript theme={null}
span.setAttributes({ dex: 'uniswap', pair: 'ETH/USDC', amountIn: '1.5' });
```

***

### addEvent()

Record an [event](/concepts/events) nested under this span.

```typescript theme={null}
addEvent(name: string, details?: string | object, options?: AddEventOptions): Span
```

#### Parameters

| Parameter | Type               | Required | Description                                         |
| --------- | ------------------ | -------- | --------------------------------------------------- |
| `name`    | `string`           | Yes      | Event name                                          |
| `details` | `string \| object` | No       | Event details (objects are stringified)             |
| `options` | `AddEventOptions`  | No       | Options with `captureStackTrace`, `timestamp`, etc. |

#### Examples

```typescript theme={null}
span.addEvent('quote_received', { price: '3200.50' });
```

***

### info() / warn() / error()

Convenience methods for recording an event under this span with a severity.

```typescript theme={null}
info(name: string, details?: string | object, options?: Omit<AddEventOptions, 'severity'>): Span
warn(name: string, details?: string | object, options?: Omit<AddEventOptions, 'severity'>): Span
error(name: string, details?: string | object, options?: Omit<AddEventOptions, 'severity'>): Span
```

#### Examples

```typescript theme={null}
span.info('step_started', { index: 0 });
span.warn('retrying', { attempt: 2 });
span.error('step_failed', { code: 'REVERT' });
```

***

### startSpan()

Open a child span parented to this span.

```typescript theme={null}
startSpan(name: string, options?: SpanOptions): Span
```

#### Parameters

| Parameter | Type          | Required | Description                                |
| --------- | ------------- | -------- | ------------------------------------------ |
| `name`    | `string`      | Yes      | Child span name                            |
| `options` | `SpanOptions` | No       | Initial `attributes` (parent is this span) |

#### Examples

```typescript theme={null}
const parent = trace.startSpan('checkout');
const charge = parent.startSpan('charge');
// ... work ...
charge.end({ status: 'OK' });
parent.end({ status: 'OK' });
```

***

### end()

End the span, optionally setting an OTLP status and message. Idempotent — a second call is ignored.

```typescript theme={null}
end(options?: SpanEndOptions): void
```

#### SpanEndOptions

| Option    | Type                         | Description                                    |
| --------- | ---------------------------- | ---------------------------------------------- |
| `status`  | `'OK' \| 'ERROR' \| 'UNSET'` | Terminal span status (omit for `UNSET`)        |
| `message` | `string`                     | Status message, typically an error description |

#### Examples

```typescript theme={null}
span.end();                                          // UNSET
span.end({ status: 'OK' });
span.end({ status: 'ERROR', message: 'quote timed out' });
```

***

### isEnded()

Whether `end()` has been called.

```typescript theme={null}
isEnded(): boolean
```

## Method Chaining

`setAttribute`, `setAttributes`, `addEvent`, `info`, `warn`, and `error` return the span for chaining:

```typescript theme={null}
const span = trace.startSpan('swap', { attributes: { dex: 'uniswap' } });

span.setAttribute('amountIn', '1.5')
    .info('quote_requested')
    .info('quote_received', { price: '3200.50' });

span.end({ status: 'OK' });
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Spans (Concept)" icon="layer-group" href="/concepts/spans">
    How spans nest and time work
  </Card>

  <Card title="Trace" icon="route" href="/api-reference/trace">
    startSpan() and span() on the trace
  </Card>
</CardGroup>