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<A> = Option.None<A> | Option.Some<A>The Option data type represents optional values. An Option<A> is either
Some<A>, containing a value of type A, or None, representing absence.
When to use
Use to represent initial values that may not yet exist
- Returning from partial functions (not defined for all inputs)
- Managing optional fields in data structures
Namespace containing utility types for Option.
When to use
Use to access type-level helpers associated with Option.
Option<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;
}
import ContextContext.interface Context<in Services>Immutable collection of service implementations used for dependency
injection in Effect programs.
Details
The type parameter tracks the service identifiers available in the context.
At runtime, services are stored by each key's string key.
Example (Creating a context with multiple services)
import { Context } from "effect"
// Create a context with multiple services
const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
const Database = Context.Service<{ query: (sql: string) => string }>(
"Database"
)
const context = Context.make(Logger, {
log: (msg: string) => console.log(msg)
})
.pipe(Context.add(Database, { query: (sql) => `Result: ${sql}` }))
Context<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
}
name: stringname: string
readonly parent: Option.Option<AnySpan>parent: import OptionOption.type Option<A> = Option.None<A> | Option.Some<A>The Option data type represents optional values. An Option<A> is either
Some<A>, containing a value of type A, or None, representing absence.
When to use
Use to represent initial values that may not yet exist
- Returning from partial functions (not defined for all inputs)
- Managing optional fields in data structures
Namespace containing utility types for Option.
When to use
Use to access type-level helpers associated with Option.
Option<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;
}
import ContextContext.interface Context<in Services>Immutable collection of service implementations used for dependency
injection in Effect programs.
Details
The type parameter tracks the service identifiers available in the context.
At runtime, services are stored by each key's string key.
Example (Creating a context with multiple services)
import { Context } from "effect"
// Create a context with multiple services
const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
const Database = Context.Service<{ query: (sql: string) => string }>(
"Database"
)
const context = Context.make(Logger, {
log: (msg: string) => console.log(msg)
})
.pipe(Context.add(Database, { query: (sql) => `Result: ${sql}` }))
Context<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
}
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
}
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;
}
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
}
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;
}
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
}
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
}
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
}
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
}
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
}
startTime: bigintstartTime
}
this.NativeSpan.attributes: Map<string, unknown>attributes = new var Map: MapConstructor
new () => Map<any, any> (+3 overloads)
NativeSpan.traceId: stringtraceId = import OptionOption.const getOrUndefined: <A>(
self: Option<A>
) => A | undefined
Extracts the value from a Some, or returns undefined for None.
When to use
Use when you need to pass absent Option values to APIs that expect
undefined.
Details
Some → the inner valueNone → undefined
Example (Unwrapping to undefined)
import { Option } from "effect"
console.log(Option.getOrUndefined(Option.some(1)))
// Output: 1
console.log(Option.getOrUndefined(Option.none()))
// Output: undefined
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
}
parent: Option.Option<AnySpan>parent)?.traceId: string | undefinedtraceId ?? const randomHexString: (
length: number
) => string
NativeSpan.spanId: stringspanId = const randomHexString: (
length: number
) => string
NativeSpan.end(endTime: bigint, exit: Exit.Exit<unknown, unknown>): voidend(endTime: bigintendTime: bigint, exit: Exit.Exit<unknown, unknown>exit: import ExitExit.type Exit<A, E = never> = Exit.Success<A, E> | Exit.Failure<A, E>Represents the result of an Effect computation.
When to use
Use when you need to synchronously inspect whether an Effect computation
succeeded or failed.
Details
An Exit<A, E> is either Success<A, E> containing a value of type A, or
Failure<A, E> containing a Cause<E> describing why the computation
failed.
Since Exit is also an Effect, you can yield it inside Effect.gen.
Example (Pattern matching on an Exit)
import { Exit } from "effect"
const success: Exit.Exit<number> = Exit.succeed(42)
const failure: Exit.Exit<number, string> = Exit.fail("error")
const result = Exit.match(success, {
onSuccess: (value) => `Got value: ${value}`,
onFailure: (cause) => `Got error: ${cause}`
})
Namespace containing helper types shared by Exit values.
When to use
Use to reference helper types that describe the shared structure of Exit
values.
Exit<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)
}
}