Tracer
Defines the low-level tracing model used by Effect.
A span records the lifetime of an operation, including its name, parent, attributes, links, annotations, sampling decision, kind, and completion status. The module also defines the tracer service, parent-span context, external span support, trace propagation settings, and the default in-memory span implementation.
Constants
ParentSpanKey
Signature
declare const ParentSpanKey: "effect/Tracer/ParentSpan";Defines the string key for the active tracer context reference.
When to use
Use when you need the raw context key for active tracer lookup in lower-level tracing code.
Signature
declare const TracerKey: "effect/Tracer";Constructors
externalSpan
Creates an ExternalSpan from trace and span identifiers, defaulting sampled to true and annotations to an empty context when they are not provided.
Signature
declare function externalSpan(options: {
readonly annotations?: Context<never>;
readonly sampled?: boolean;
readonly spanId: string;
readonly traceId: string;
}): ExternalSpan;Creates a Tracer value from a tracer implementation object.
When to use
Use to create a custom tracing backend value that Effect can use when creating spans.
Details
make returns the supplied implementation object unchanged. The object must satisfy the Tracer contract, including a span method that returns a Span.
See
Spanfor the span values returned by tracer implementations
Signature
declare function make(options: Tracer): Tracer;Models
A span value that can participate in tracing, either an Effect-managed Span or an ExternalSpan propagated from another tracing system.
Signature
type AnySpan = Span | ExternalSpan;EffectPrimitive interface
A low-level Effect primitive that can be evaluated by a tracer-specific context for the current fiber.
Signature
interface EffectPrimitive<X> {
"~effect/Effect/evaluate"(this: EffectPrimitive<X>, fiber: Fiber<any, any>): X;
}ExternalSpan interface
Represents a span created outside Effect's tracer, carrying trace and span identifiers, sampling state, and annotations so it can be used as a parent or link in Effect tracing.
Signature
interface ExternalSpan {
readonly _tag: "ExternalSpan";
readonly annotations: Context<never>;
readonly sampled: boolean;
readonly spanId: string;
readonly traceId: string;
}NativeSpan
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.
See
Spanfor the interface implemented by native spans
Signature
declare class NativeSpan implements Span {
constructor(options: {
readonly annotations: Context<never>;
readonly kind: SpanKind;
readonly links: Array<SpanLink>;
readonly name: string;
readonly parent: Option<AnySpan>;
readonly sampled: boolean;
readonly startTime: bigint;
});
readonly _tag: "Span";
readonly annotations: Context<never>;
attributes: Map<string, unknown>;
events: Array<[name: string, startTime: bigint, attributes: Record<string, unknown>]>;
readonly kind: SpanKind;
readonly links: Array<SpanLink>;
readonly name: string;
readonly parent: Option<AnySpan>;
readonly sampled: boolean;
readonly spanId: string;
readonly startTime: bigint;
status: SpanStatus;
readonly traceId: string;
addLinks(links: readonly Array<SpanLink>): void;
attribute(key: string, value: unknown): void;
end(endTime: bigint, exit: Exit<unknown, unknown>): void;
event(name: string, startTime: bigint, attributes?: Record<string, unknown>): void;
}A span created by an Effect tracer. It carries trace identity, parent, annotations, attributes, links, sampling and kind information, lifecycle status, and methods to end the span or add attributes, events, and links.
Signature
interface Span {
readonly _tag: "Span";
readonly annotations: Context<never>;
readonly attributes: ReadonlyMap<string, unknown>;
readonly kind: SpanKind;
readonly links: readonly Array<SpanLink>;
readonly name: string;
readonly parent: Option<AnySpan>;
readonly sampled: boolean;
readonly spanId: string;
readonly status: SpanStatus;
readonly traceId: string;
addLinks(links: readonly Array<SpanLink>): void;
attribute(key: string, value: unknown): void;
end(endTime: bigint, exit: Exit<unknown, unknown>): void;
event(name: string, startTime: bigint, attributes?: Record<string, unknown>): void;
}OpenTelemetry-style role describing the kind of operation represented by a span: internal work, server handling, client calls, producing, or consuming.
Signature
type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";A relationship from one span to another span, with attributes describing the relationship.
Signature
interface SpanLink {
readonly attributes: Readonly<Record<string, unknown>>;
readonly span: AnySpan;
}SpanStatus type
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.
Signature
type SpanStatus =
| {
_tag: "Started";
startTime: bigint;
}
| {
_tag: "Ended";
endTime: bigint;
exit: Exit.Exit<unknown, unknown>;
startTime: bigint;
};Options
SpanOptions interface
Options accepted by span-creating APIs, combining span metadata such as attributes, links, parent/root selection, kind, sampling, and trace level with stack trace capture settings.
Signature
interface SpanOptions extends SpanOptionsNoTrace, TraceOptions {}SpanOptionsNoTrace interface
Span creation options that do not control stack trace capture, including attributes, links, parent or root selection, annotations, span kind, sampling, and the trace level used for filtering.
Signature
interface SpanOptionsNoTrace {
readonly annotations?: Context<never>;
readonly attributes?: Record<string, unknown>;
readonly kind?: SpanKind;
readonly level?: LogLevel;
readonly links?: readonly Array<SpanLink>;
readonly parent?: AnySpan;
readonly root?: boolean;
readonly sampled?: boolean;
}TraceOptions interface
Options that control stack trace capture for tracing wrappers. captureStackTrace can disable capture or provide a lazy stack string.
Signature
interface TraceOptions {
readonly captureStackTrace?: boolean | LazyArg<string | undefined>;
}Services
CurrentTraceLevel
Context reference for controlling the current trace level for dynamic filtering.
When to use
Use to set the default trace level for spans in a scope when span options do not provide level.
Details
The default value is "Info". Span creation uses options.level ?? CurrentTraceLevel before applying MinimumTraceLevel.
See
MinimumTraceLevelfor the threshold that decides whether spans at that level are sampled
Signature
declare const CurrentTraceLevel: Context.Reference<LogLevel>;DisablePropagation
Context reference for disabling trace propagation.
When to use
Use to prevent spans in a scope from propagating tracing context.
Details
When enabled on fiber or span annotations, new spans are created as non-propagating no-op spans and disabled spans are skipped when deriving a parent span.
Signature
declare const DisablePropagation: Reference<boolean>;MinimumTraceLevel
Context reference for setting the minimum trace level threshold. Spans and their descendants below this level will have their sampling decision forced to false, preventing them from being exported.
When to use
Use to set the trace-level threshold that controls whether spans are sampled by default.
Details
The default value is "All". Span creation compares the span level from options.level ?? CurrentTraceLevel against this threshold.
Gotchas
Explicit options.sampled bypasses threshold computation.
See
CurrentTraceLevelfor the default span level used when options do not specify one
Signature
declare const MinimumTraceLevel: Reference<LogLevel>;ParentSpan
Context service containing the Span or ExternalSpan to use as the parent of newly-created child spans.
Signature
declare class ParentSpan extends Shape<"effect/Tracer/ParentSpan", AnySpan, this> {
constructor(_: never);
}Context reference for the active tracer service. By default it uses the native tracer, which creates NativeSpan instances.
Signature
declare const Tracer: Reference<Tracer>;A tracing backend used by Effect to create spans. Custom tracers implement span to allocate a span from the supplied name, parent, annotations, links, start time, kind, root flag, and sampling decision.
Signature
interface Tracer {
readonly context?: <X>(primitive: EffectPrimitive<X>, fiber: Fiber<any, any>) => X;
span(
this: Tracer,
options: {
readonly annotations: Context<never>;
readonly kind: SpanKind;
readonly links: Array<SpanLink>;
readonly name: string;
readonly parent: Option<AnySpan>;
readonly root: boolean;
readonly sampled: boolean;
readonly startTime: bigint;
},
): Span;
}
Defines the string key for the parent-span context service.
When to use
Use when you need the raw context key for parent span lookup in lower-level tracing code.