> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/getsentry/sentry-javascript/llms.txt
> Use this file to discover all available pages before exploring further.

# Span Types

> TypeScript interfaces for distributed tracing spans

Span types define the structure of spans used in distributed tracing.

## Span Interface

From `packages/core/src/types-hoist/span.ts`:

```typescript theme={null}
export interface Span {
  spanContext(): SpanContextData;
  end(endTimestamp?: SpanTimeInput): void;
  setAttribute(key: string, value: SpanAttributeValue | undefined): this;
  setAttributes(attributes: SpanAttributes): this;
  setStatus(status: SpanStatus): this;
  updateName(name: string): this;
  isRecording(): boolean;
}
```

## SpanContextData

```typescript theme={null}
export interface SpanContextData {
  traceId: string;
  spanId: string;
  isRemote?: boolean | undefined;
  traceFlags: TraceFlag | number;
  traceState?: TraceState | undefined;
}
```

### Fields

<ResponseField name="traceId" type="string" required>
  32-character hex string (128 bits) representing the trace.

  ```typescript theme={null}
  traceId: '1234567890abcdef1234567890abcdef'
  ```
</ResponseField>

<ResponseField name="spanId" type="string" required>
  16-character hex string (64 bits) representing the span.

  ```typescript theme={null}
  spanId: '1234567890abcdef'
  ```
</ResponseField>

<ResponseField name="traceFlags" type="number" required>
  Trace flags bitmap. `1` = sampled, `0` = not sampled.

  ```typescript theme={null}
  traceFlags: 1 // Span is sampled
  ```
</ResponseField>

<ResponseField name="isRemote" type="boolean">
  Whether the span was propagated from a remote parent.

  ```typescript theme={null}
  isRemote: true
  ```
</ResponseField>

## SpanJSON

Serialized span format:

```typescript theme={null}
export interface SpanJSON {
  data: SpanAttributes;
  description?: string;
  op?: string;
  parent_span_id?: string;
  span_id: string;
  start_timestamp: number;
  status?: string;
  timestamp?: number;
  trace_id: string;
  origin?: SpanOrigin;
  profile_id?: string;
  exclusive_time?: number;
  measurements?: Measurements;
  is_segment?: boolean;
  segment_id?: string;
}
```

### Fields

<ResponseField name="span_id" type="string" required>
  Unique span identifier (16 hex characters).
</ResponseField>

<ResponseField name="trace_id" type="string" required>
  Trace identifier (32 hex characters).
</ResponseField>

<ResponseField name="parent_span_id" type="string">
  Parent span identifier, if this is a child span.
</ResponseField>

<ResponseField name="op" type="string">
  Span operation type (e.g., `'http.client'`, `'db.query'`).
</ResponseField>

<ResponseField name="description" type="string">
  Human-readable description of the span.
</ResponseField>

<ResponseField name="start_timestamp" type="number" required>
  Unix timestamp (seconds) when span started.
</ResponseField>

<ResponseField name="timestamp" type="number">
  Unix timestamp (seconds) when span ended.
</ResponseField>

<ResponseField name="status" type="string">
  Span status: `'ok'`, `'cancelled'`, `'unknown'`, etc.
</ResponseField>

<ResponseField name="data" type="SpanAttributes" required>
  Span attributes (key-value pairs).
</ResponseField>

## SpanAttributes

```typescript theme={null}
export type SpanAttributeValue =
  | string
  | number
  | boolean
  | Array<null | undefined | string>
  | Array<null | undefined | number>
  | Array<null | undefined | boolean>;

export type SpanAttributes = Partial<{
  'sentry.origin': string;
  'sentry.op': string;
  'sentry.source': TransactionSource;
  'sentry.sample_rate': number;
}> & Record<string, SpanAttributeValue | undefined>;
```

### Example

```typescript theme={null}
const attributes: SpanAttributes = {
  'http.method': 'GET',
  'http.url': 'https://api.example.com/users',
  'http.status_code': 200,
  'http.request.body.size': 0,
  'http.response.body.size': 1024,
  'user.id': '123',
  'custom.tag': 'value'
};
```

## SpanStatus

```typescript theme={null}
export interface SpanStatus {
  code: SpanStatusType;
  message?: string;
}

export enum SpanStatusType {
  Unset = 0,
  Ok = 1,
  Error = 2,
}
```

### Status Codes

<ResponseField name="0" type="Unset">
  Status not set.
</ResponseField>

<ResponseField name="1" type="Ok">
  Operation completed successfully.
</ResponseField>

<ResponseField name="2" type="Error">
  Operation failed.
</ResponseField>

### Example

```typescript theme={null}
import { SPAN_STATUS_OK, SPAN_STATUS_ERROR } from '@sentry/core';

// Success
span.setStatus({ code: SPAN_STATUS_OK });

// Error with message
span.setStatus({ 
  code: SPAN_STATUS_ERROR, 
  message: 'Connection timeout' 
});
```

## SpanOrigin

Indicates how the span was created:

```typescript theme={null}
type SpanOriginType = 'manual' | 'auto';
type SpanOriginCategory = string;
type SpanOriginIntegrationName = string;
type SpanOriginIntegrationPart = string;

export type SpanOrigin =
  | SpanOriginType
  | `${SpanOriginType}.${SpanOriginCategory}`
  | `${SpanOriginType}.${SpanOriginCategory}.${SpanOriginIntegrationName}`
  | `${SpanOriginType}.${SpanOriginCategory}.${SpanOriginIntegrationName}.${SpanOriginIntegrationPart}`;
```

### Examples

```typescript theme={null}
origin: 'manual' // Manually created
origin: 'auto.http' // Auto-instrumented HTTP
origin: 'auto.db.prisma' // Prisma integration
origin: 'auto.http.fetch.browser' // Browser fetch
```

## SentrySpanArguments

Arguments for creating spans:

```typescript theme={null}
export interface SentrySpanArguments {
  name?: string | undefined;
  op?: string | undefined;
  parentSpanId?: string | undefined;
  sampled?: boolean | undefined;
  spanId?: string | undefined;
  traceId?: string | undefined;
  attributes?: SpanAttributes;
  startTimestamp?: number | undefined;
  endTimestamp?: number | undefined;
  links?: SpanLink[];
  isStandalone?: boolean | undefined;
}
```

## StartSpanOptions

Options for starting a span:

```typescript theme={null}
export interface StartSpanOptions {
  name: string;
  op?: string;
  attributes?: SpanAttributes;
  startTime?: SpanTimeInput;
  scope?: Scope;
  parentSpan?: Span | null;
  onlyIfParent?: boolean;
  forceTransaction?: boolean;
}
```

### Fields

<ParamField path="name" type="string" required>
  Span description.
</ParamField>

<ParamField path="op" type="string">
  Span operation type.
</ParamField>

<ParamField path="attributes" type="SpanAttributes">
  Initial span attributes.
</ParamField>

<ParamField path="startTime" type="SpanTimeInput">
  Custom start time (Date, number, or HrTime).
</ParamField>

<ParamField path="parentSpan" type="Span">
  Explicit parent span.
</ParamField>

<ParamField path="onlyIfParent" type="boolean">
  Only create span if there's a parent.
</ParamField>

## Complete Example

```typescript theme={null}
import * as Sentry from '@sentry/node';

const spanJSON: SpanJSON = {
  span_id: '1234567890abcdef',
  trace_id: '1234567890abcdef1234567890abcdef',
  parent_span_id: 'fedcba0987654321',
  
  op: 'http.client',
  description: 'GET https://api.example.com/users',
  
  start_timestamp: 1234567890.0,
  timestamp: 1234567891.5,
  
  status: 'ok',
  
  data: {
    'http.method': 'GET',
    'http.url': 'https://api.example.com/users',
    'http.status_code': 200,
    'http.request.body.size': 0,
    'http.response.body.size': 1024,
    'sentry.origin': 'auto.http.fetch',
    'sentry.op': 'http.client'
  },
  
  origin: 'auto.http.fetch',
  
  measurements: {
    'http.response_transfer_size': {
      value: 1024,
      unit: 'byte'
    },
    'http.response_content_length': {
      value: 1024,
      unit: 'byte'
    }
  }
};
```

## Semantic Conventions

### HTTP Spans

```typescript theme={null}
const httpSpan: SpanAttributes = {
  'http.method': 'POST',
  'http.url': 'https://api.example.com/users',
  'http.status_code': 201,
  'http.request.body.size': 256,
  'http.response.body.size': 512,
  'http.flavor': '1.1',
  'net.peer.name': 'api.example.com',
  'net.peer.port': 443
};
```

### Database Spans

```typescript theme={null}
const dbSpan: SpanAttributes = {
  'db.system': 'postgresql',
  'db.name': 'myapp',
  'db.statement': 'SELECT * FROM users WHERE id = $1',
  'db.operation': 'SELECT',
  'db.user': 'app_user',
  'net.peer.name': 'localhost',
  'net.peer.port': 5432
};
```

### Custom Attributes

```typescript theme={null}
const customSpan: SpanAttributes = {
  'user.id': '123',
  'feature.flag': 'new-ui',
  'cache.hit': true,
  'retry.count': 3,
  'queue.message_id': 'msg-456',
  'custom.metric': 42.5
};
```

## Related

* [Spans](/api/tracing/spans)
* [Trace Context](/api/tracing/trace-context)
* [Event Types](/api/types/event)