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:

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

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

Fields

traceId · string · required

32-character hex string (128 bits) representing the trace.

traceId: '1234567890abcdef1234567890abcdef'

spanId · string · required

16-character hex string (64 bits) representing the span.

spanId: '1234567890abcdef'

traceFlags · number · required

Trace flags bitmap. 1 = sampled, 0 = not sampled.

traceFlags: 1 // Span is sampled

isRemote · boolean

Whether the span was propagated from a remote parent.

isRemote: true

SpanJSON

Serialized span format:

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

span_id · string · required

Unique span identifier (16 hex characters).

trace_id · string · required

Trace identifier (32 hex characters).

parent_span_id · string

Parent span identifier, if this is a child span.

op · string

Span operation type (e.g., 'http.client', 'db.query').

description · string

Human-readable description of the span.

start_timestamp · number · required

Unix timestamp (seconds) when span started.

timestamp · number

Unix timestamp (seconds) when span ended.

status · string

Span status: 'ok', 'cancelled', 'unknown', etc.

data · SpanAttributes · required

Span attributes (key-value pairs).

SpanAttributes

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

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

export interface SpanStatus {
  code: SpanStatusType;
  message?: string;
}

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

Status Codes

0 · Unset

Status not set.

1 · Ok

Operation completed successfully.

2 · Error

Operation failed.

Example

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:

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

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:

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:

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

Fields

name · string · required

Span description.

op · string

Span operation type.

attributes · SpanAttributes

Initial span attributes.

startTime · SpanTimeInput

Custom start time (Date, number, or HrTime).

parentSpan · Span

Explicit parent span.

onlyIfParent · boolean

Only create span if there’s a parent.

Complete Example

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

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

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

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
• Trace Context
• Event Types