References
The References module exposes the built-in Context.Reference keys that the Effect runtime consults for execution settings and diagnostic metadata. These references cover concurrency, scheduling, logging, tracing, and low-level diagnostic state.
A Context.Reference<A> is a service key with a default value. Reading one of these references returns the value from the current fiber context, and providing a new value changes behavior for the provided effect and the fibers it starts.
References
CurrentLogAnnotations
Signature
declare const CurrentLogAnnotations: Context.Reference<ReadonlyRecord<string, unknown>>;CurrentLoggers
Context reference for the set of loggers currently used by Effect logging operations.
When to use
Use to inspect or provide the complete set of loggers used by Effect logging in the current context.
Details
The default set contains the built-in default logger and tracer logger. Providing this reference changes which Logger instances receive log entries in the current context.
Signature
declare const CurrentLoggers: Context.Reference<ReadonlySet<Logger<unknown, any>>>;CurrentLogLevel
Context reference for the current log severity used by Effect.log when no explicit level is provided.
When to use
Use to set the default severity for Effect.log entries that do not provide an explicit level.
Details
Use MinimumLogLevel to control which log entries are filtered out.
Signature
declare const CurrentLogLevel: Context.Reference<Severity>;CurrentLogSpans
Context reference for managing log spans that track the duration and hierarchy of operations. Each span represents a labeled time period for performance analysis and debugging.
When to use
Use to carry the active log span stack that should be included with log entries in the current context.
Signature
declare const CurrentLogSpans: Context.Reference<ReadonlyArray<[label: string, timestamp: number]>>;CurrentStackFrame
Context reference for the current captured stack-frame chain for the running fiber.
When to use
Use when writing low-level tracing or diagnostic integrations that need direct access to the stack-frame chain carried by the current fiber.
Details
Effect and Layer tracing use this reference to attach stack-frame information to failures and interruption causes. It is normally managed by tracing APIs rather than provided directly by application code.
See
StackFramefor the frame node stored in this reference
Signature
declare const CurrentStackFrame: Context.Reference<StackFrame | undefined>;LogToStderr
Context reference for controlling whether built-in console loggers write to stderr.
When to use
Use to configure the runtime reference that controls whether built-in console loggers write to stderr.
Details
The default value is false. When set to true, the built-in default logger and TTY pretty console logger call console.error instead of console.log.
Signature
declare const LogToStderr: Context.Reference<boolean>;MinimumLogLevel
Context reference for setting the minimum log level threshold. Log entries below this level will be filtered out completely.
When to use
Use to filter out log entries below a severity threshold.
Signature
declare const MinimumLogLevel: Context.Reference<LogLevel>;StackFrame interface
A captured stack-frame node used to describe the traced execution path.
When to use
Use when reading or supplying the stack-frame chain that Effect tracing uses to attach diagnostic call-site information to failures and interruptions.
Details
Each frame has a span or operation name, a lazy stack supplier, and an optional parent frame that links it to the previous captured frame.
See
CurrentStackFramefor the fiber reference carrying the active stack-frame chain
Signature
interface StackFrame {
readonly name: string;
readonly parent: StackFrame | undefined;
readonly stack: () => string | undefined;
}TracerEnabled
Context reference for controlling whether tracing is enabled globally. When set to false, spans will not be registered with the tracer and tracing overhead is minimized.
When to use
Use to disable or re-enable span registration in the current context.
Signature
declare const TracerEnabled: Context.Reference<boolean>;TracerSpanAnnotations
Context reference for managing span annotations that are automatically added to all new spans. These annotations provide context and metadata that applies across multiple spans.
When to use
Use to attach shared metadata to every span created in the current context.
Signature
declare const TracerSpanAnnotations: Context.Reference<ReadonlyRecord<string, unknown>>;TracerSpanLinks
Context reference for managing span links that are automatically added to all new spans. Span links connect related spans that are not in a parent-child relationship.
When to use
Use to attach shared links to every span created in the current context.
Signature
declare const TracerSpanLinks: Context.Reference<ReadonlyArray<SpanLink>>;TracerTimingEnabled
Context reference for controlling whether trace timing is enabled globally. When set to false, spans will not contain timing information (trace time will always be set to zero).
When to use
Use to disable or re-enable timing capture for spans in the current context.
Signature
declare const TracerTimingEnabled: Context.Reference<boolean>;UnhandledLogLevel
Context reference for the log severity used when a pool finalizer reports an unhandled error.
When to use
Use to choose whether and at which severity pool finalizer failures are reported.
Details
The default level is "Error".
Gotchas
Providing undefined suppresses this report; it does not fall back to CurrentLogLevel.
See
CurrentLogLevelfor the default severity used by ordinaryEffect.logcallsMinimumLogLevelfor filtering emitted log entries by threshold
Signature
declare const UnhandledLogLevel: Context.Reference<Severity | 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>;MaxOpsBeforeYield
Context reference that controls the maximum number of operations a fiber can perform before yielding control back to the scheduler.
When to use
Use to tune scheduler fairness for CPU-bound fibers by changing the scheduler operation budget that triggers a yield.
Details
The default value is 2048 operations, which balances performance and fairness by helping prevent long-running fibers from monopolizing the execution thread.
See
PreventSchedulerYieldfor bypassing scheduler yield checks entirely rather than tuning the operation budget
Signature
declare const MaxOpsBeforeYield: Reference<number>;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>;PreventSchedulerYield
Context reference that controls whether the runtime should bypass scheduler yield checks. When set to true, the fiber run loop won't call Scheduler.shouldYield.
When to use
Use to bypass scheduler yield checks for controlled runtime workloads where cooperative yielding should be disabled.
Gotchas
Setting this reference to true can let long-running fibers monopolize the JavaScript thread.
See
MaxOpsBeforeYieldfor tuning yield frequency without disabling yield checksSchedulerfor providing custom scheduler yield behavior
Signature
declare const PreventSchedulerYield: Reference<boolean>;Context reference for the scheduler used by the Effect runtime.
When to use
Use when you need to replace scheduling behavior globally in tests or runtime setup, such as forcing deterministic task dispatch.
Details
The default value creates a MixedScheduler. Provide this service to customize execution mode, task dispatching, or yield behavior.
Signature
declare const Scheduler: Reference<Scheduler>;A scheduler manages the execution of Effect fibers by controlling when queued tasks run.
When to use
Use to define or provide custom runtime scheduling behavior for Effect fibers.
Details
A scheduler determines the execution mode, schedules tasks with different priorities, and decides when fibers should yield control after consuming their operation budget.
Signature
interface Scheduler {
readonly executionMode: "sync" | "async";
makeDispatcher(): SchedulerDispatcher;
shouldYield(fiber: Fiber<unknown, unknown>): boolean;
}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;
}
Context reference for managing log annotations that are automatically added to all log entries. These annotations provide contextual metadata that appears in every log message.
When to use
Use to attach shared contextual metadata to every log entry emitted in the current context.