NativeSpanDefault in-memory Span implementation used by the native tracer. It
generates span and trace identifiers, stores attributes, events, and links,
and records Started or Ended status.
Details
The constructor initializes the span with Started status, inherits the
parent trace id or generates a new one, and always generates a new span id.
Attributes, events, links, and status are then mutated through Span methods.
export class class NativeSpanclass NativeSpan {
_tag: 'Span';
spanId: string;
traceId: string;
sampled: boolean;
name: string;
parent: Option.Option<AnySpan>;
annotations: Context.Context<never>;
links: Array<SpanLink>;
startTime: bigint;
kind: SpanKind;
status: SpanStatus;
attributes: Map<string, unknown>;
events: Array<[name: string, startTime: bigint, attributes: Record<string, unknown>]>;
end: (endTime: bigint, exit: Exit.Exit<unknown, unknown>) => void;
attribute: (key: string, value: unknown) => void;
event: (name: string, startTime: bigint, attributes?: Record<string, unknown>) => void;
addLinks: (links: ReadonlyArray<SpanLink>) => void;
}
Default in-memory Span implementation used by the native tracer. It
generates span and trace identifiers, stores attributes, events, and links,
and records Started or Ended status.
Details
The constructor initializes the span with Started status, inherits the
parent trace id or generates a new one, and always generates a new span id.
Attributes, events, links, and status are then mutated through Span methods.
NativeSpan implements Span {
readonly NativeSpan._tag: "Span"_tag = "Span"
readonly NativeSpan.spanId: stringspanId: string
readonly NativeSpan.traceId: stringtraceId: string = "native"
readonly NativeSpan.sampled: booleansampled: boolean
readonly NativeSpan.name: stringname: string
readonly NativeSpan.parent: Option.Option<AnySpan>parent: import OptionOption.type Option.Option = /*unresolved*/ anyOption<type AnySpan = Span | ExternalSpanA span value that can participate in tracing, either an Effect-managed
Span or an ExternalSpan propagated from another tracing system.
Example (Accepting any span)
import { Effect, Tracer } from "effect"
// Function that accepts any span type
const logSpan = (span: Tracer.AnySpan) => {
console.log(`Span ID: ${span.spanId}, Trace ID: ${span.traceId}`)
return Effect.succeed(span)
}
// Works with both Span and ExternalSpan
const externalSpan = Tracer.externalSpan({
spanId: "span-123",
traceId: "trace-456"
})
AnySpan>
readonly NativeSpan.annotations: Context.Context<never>(property) NativeSpan.annotations: {
mapUnsafe: ReadonlyMap<string, any>;
mutable: boolean;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
annotations: import ContextContext.type Context.Context = /*unresolved*/ anyContext<never>
readonly NativeSpan.links: Array<SpanLink>links: interface Array<T>Array<SpanLink>
readonly NativeSpan.startTime: bigintstartTime: bigint
readonly NativeSpan.kind: SpanKindkind: type SpanKind =
| "internal"
| "server"
| "client"
| "producer"
| "consumer"
OpenTelemetry-style role describing the kind of operation represented by a
span: internal work, server handling, client calls, producing, or consuming.
Example (Configuring span kinds)
import { Effect } from "effect"
import type { Tracer } from "effect"
// Different span kinds for different operations
const serverSpan = Effect.withSpan("handle-request", {
kind: "server" as Tracer.SpanKind
})
const clientSpan = Effect.withSpan("api-call", {
kind: "client" as Tracer.SpanKind
})
const internalSpan = Effect.withSpan("internal-process", {
kind: "internal" as Tracer.SpanKind
})
SpanKind
NativeSpan.status: SpanStatusstatus: type SpanStatus =
| {
_tag: "Started"
startTime: bigint
}
| {
_tag: "Ended"
startTime: bigint
endTime: bigint
exit: Exit.Exit<unknown, unknown>
}
Lifecycle state of a span, where Started records the start time and
Ended records the start time, end time, and exit value with which the span
completed.
Example (Creating span statuses)
import { Exit } from "effect"
import type { Tracer } from "effect"
const startTime = 1_000_000_000n
const endTime = 1_500_000_000n
const startedStatus: Tracer.SpanStatus = {
_tag: "Started",
startTime
}
const endedStatus: Tracer.SpanStatus = {
_tag: "Ended",
startTime,
endTime,
exit: Exit.succeed("result")
}
console.log(startedStatus._tag) // "Started"
console.log(endedStatus.endTime - endedStatus.startTime) // 500000000n
SpanStatus
NativeSpan.attributes: Map<string, unknown>attributes: interface Map<K, V>Map<string, unknown>
NativeSpan.events: [name: string, startTime: bigint, attributes: Record<string, unknown>][]events: interface Array<T>Array<[stringname: string, bigintstartTime: bigint, Record<string, unknown>attributes: type Record<K extends keyof any, T> = {
[P in K]: T
}
Construct a type with a set of properties K of type T
Record<string, unknown>]> = []
constructor(options: {
readonly name: string
readonly parent: Option.Option<AnySpan>
readonly annotations: Context.Context<never>
readonly links: Array<SpanLink>
readonly startTime: bigint
readonly kind: SpanKind
readonly sampled: boolean
}
options: {
readonly name: stringname: string
readonly parent: Option.Option<AnySpan>parent: import OptionOption.type Option.Option = /*unresolved*/ anyOption<type AnySpan = Span | ExternalSpanA span value that can participate in tracing, either an Effect-managed
Span or an ExternalSpan propagated from another tracing system.
Example (Accepting any span)
import { Effect, Tracer } from "effect"
// Function that accepts any span type
const logSpan = (span: Tracer.AnySpan) => {
console.log(`Span ID: ${span.spanId}, Trace ID: ${span.traceId}`)
return Effect.succeed(span)
}
// Works with both Span and ExternalSpan
const externalSpan = Tracer.externalSpan({
spanId: "span-123",
traceId: "trace-456"
})
AnySpan>
readonly annotations: Context.Context<never>(property) annotations: {
mapUnsafe: ReadonlyMap<string, any>;
mutable: boolean;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
annotations: import ContextContext.type Context.Context = /*unresolved*/ anyContext<never>
readonly links: Array<SpanLink>links: interface Array<T>Array<SpanLink>
readonly startTime: bigintstartTime: bigint
readonly kind: SpanKindkind: type SpanKind =
| "internal"
| "server"
| "client"
| "producer"
| "consumer"
OpenTelemetry-style role describing the kind of operation represented by a
span: internal work, server handling, client calls, producing, or consuming.
Example (Configuring span kinds)
import { Effect } from "effect"
import type { Tracer } from "effect"
// Different span kinds for different operations
const serverSpan = Effect.withSpan("handle-request", {
kind: "server" as Tracer.SpanKind
})
const clientSpan = Effect.withSpan("api-call", {
kind: "client" as Tracer.SpanKind
})
const internalSpan = Effect.withSpan("internal-process", {
kind: "internal" as Tracer.SpanKind
})
SpanKind
readonly sampled: booleansampled: boolean
}) {
this.NativeSpan.name: stringname = options: {
readonly name: string
readonly parent: Option.Option<AnySpan>
readonly annotations: Context.Context<never>
readonly links: Array<SpanLink>
readonly startTime: bigint
readonly kind: SpanKind
readonly sampled: boolean
}
options.name: stringname
this.NativeSpan.parent: Option.Option<AnySpan>parent = options: {
readonly name: string
readonly parent: Option.Option<AnySpan>
readonly annotations: Context.Context<never>
readonly links: Array<SpanLink>
readonly startTime: bigint
readonly kind: SpanKind
readonly sampled: boolean
}
options.parent: Option.Option<AnySpan>parent
this.NativeSpan.annotations: Context.Context<never>(property) NativeSpan.annotations: {
mapUnsafe: ReadonlyMap<string, any>;
mutable: boolean;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
annotations = options: {
readonly name: string
readonly parent: Option.Option<AnySpan>
readonly annotations: Context.Context<never>
readonly links: Array<SpanLink>
readonly startTime: bigint
readonly kind: SpanKind
readonly sampled: boolean
}
options.annotations: Context.Context<never>(property) annotations: {
mapUnsafe: ReadonlyMap<string, any>;
mutable: boolean;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
annotations
this.NativeSpan.links: Array<SpanLink>links = options: {
readonly name: string
readonly parent: Option.Option<AnySpan>
readonly annotations: Context.Context<never>
readonly links: Array<SpanLink>
readonly startTime: bigint
readonly kind: SpanKind
readonly sampled: boolean
}
options.links: Array<SpanLink>links
this.NativeSpan.startTime: bigintstartTime = options: {
readonly name: string
readonly parent: Option.Option<AnySpan>
readonly annotations: Context.Context<never>
readonly links: Array<SpanLink>
readonly startTime: bigint
readonly kind: SpanKind
readonly sampled: boolean
}
options.startTime: bigintstartTime
this.NativeSpan.kind: SpanKindkind = options: {
readonly name: string
readonly parent: Option.Option<AnySpan>
readonly annotations: Context.Context<never>
readonly links: Array<SpanLink>
readonly startTime: bigint
readonly kind: SpanKind
readonly sampled: boolean
}
options.kind: SpanKindkind
this.NativeSpan.sampled: booleansampled = options: {
readonly name: string
readonly parent: Option.Option<AnySpan>
readonly annotations: Context.Context<never>
readonly links: Array<SpanLink>
readonly startTime: bigint
readonly kind: SpanKind
readonly sampled: boolean
}
options.sampled: booleansampled
this.NativeSpan.status: SpanStatusstatus = {
_tag: "Started"_tag: "Started",
startTime: bigintstartTime: options: {
readonly name: string
readonly parent: Option.Option<AnySpan>
readonly annotations: Context.Context<never>
readonly links: Array<SpanLink>
readonly startTime: bigint
readonly kind: SpanKind
readonly sampled: boolean
}
options.startTime: bigintstartTime
}
this.NativeSpan.attributes: Map<string, unknown>attributes = new var Map: MapConstructor
new () => Map<any, any> (+3 overloads)
Map()
this.NativeSpan.traceId: stringtraceId = import OptionOption.getOrUndefined(options: {
readonly name: string
readonly parent: Option.Option<AnySpan>
readonly annotations: Context.Context<never>
readonly links: Array<SpanLink>
readonly startTime: bigint
readonly kind: SpanKind
readonly sampled: boolean
}
options.parent: Option.Option<AnySpan>parent)?.traceId ?? const randomHexString: (
length: number
) => string
randomHexString(32)
this.NativeSpan.spanId: stringspanId = const randomHexString: (
length: number
) => string
randomHexString(16)
}
NativeSpan.end(endTime: bigint, exit: Exit.Exit<unknown, unknown>): voidend(endTime: bigintendTime: bigint, exit: Exit.Exit<unknown, unknown>exit: import ExitExit.type Exit.Exit = /*unresolved*/ anyExit<unknown, unknown>): void {
this.NativeSpan.status: SpanStatusstatus = {
_tag: "Ended"_tag: "Ended",
endTime: bigintendTime,
exit: Exit.Exit<unknown, unknown>exit,
startTime: bigintstartTime: this.NativeSpan.status: SpanStatusstatus.startTime: bigintstartTime
}
}
NativeSpan.attribute(key: string, value: unknown): voidattribute(key: stringkey: string, value: unknownvalue: unknown): void {
this.NativeSpan.attributes: Map<string, unknown>attributes.Map<string, unknown>.set(key: string, value: unknown): Map<string, unknown>Adds a new element with a specified key and value to the Map. If an element with the same key already exists, the element will be updated.
set(key: stringkey, value: unknownvalue)
}
NativeSpan.event(name: string, startTime: bigint, attributes?: Record<string, unknown>): voidevent(name: stringname: string, startTime: bigintstartTime: bigint, attributes: Record<string, unknown> | undefinedattributes?: type Record<K extends keyof any, T> = {
[P in K]: T
}
Construct a type with a set of properties K of type T
Record<string, unknown>): void {
this.NativeSpan.events: [name: string, startTime: bigint, attributes: Record<string, unknown>][]events.Array<[name: string, startTime: bigint, attributes: Record<string, unknown>]>.push(...items: [name: string, startTime: bigint, attributes: Record<string, unknown>][]): numberAppends new elements to the end of an array, and returns the new length of the array.
push([name: stringname, startTime: bigintstartTime, attributes: Record<string, unknown> | undefinedattributes ?? {}])
}
NativeSpan.addLinks(links: ReadonlyArray<SpanLink>): voidaddLinks(links: ReadonlyArray<SpanLink>links: interface ReadonlyArray<T>ReadonlyArray<SpanLink>): void {
// oxlint-disable-next-line no-restricted-syntax
this.NativeSpan.links: Array<SpanLink>links.Array<SpanLink>.push(...items: SpanLink[]): numberAppends new elements to the end of an array, and returns the new length of the array.
push(...links: ReadonlyArray<SpanLink>links)
}
}