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
32-character hex string (128 bits) representing the trace.traceId: '1234567890abcdef1234567890abcdef'
16-character hex string (64 bits) representing the span.spanId: '1234567890abcdef'
Trace flags bitmap. 1 = sampled, 0 = not sampled.traceFlags: 1 // Span is sampled
Whether the span was propagated from a remote parent. 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
Unique span identifier (16 hex characters).
Trace identifier (32 hex characters).
Parent span identifier, if this is a child span.
Span operation type (e.g., 'http.client', 'db.query').
Human-readable description of the span.
Unix timestamp (seconds) when span started.
Unix timestamp (seconds) when span ended.
Span status: 'ok', 'cancelled', 'unknown', etc.
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
Operation completed successfully.
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
Custom start time (Date, number, or HrTime).
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
};
