Logger
Defines loggers and log-event data for Effect programs.
A Logger<Message, Output> receives each log event as Options and turns it into output such as a formatted string, structured object, console write, file write, JSON line, or trace span event. This module also includes active logger references, console routing helpers, built-in formatters, batching, file logging, and layers for installing loggers.
Constructors
Signature
declare const batched: <Output>(options: {
readonly flush: (messages: Array<NoInfer<Output>>) => Effect<void>;
readonly window: Input;
}) => <Message>(self: Logger<Message, Output>) => Effect<Logger<Message, void>, never, Scope> & <Message, Output>(self: Logger<Message, Output>, options: {
readonly flush: (messages: Array<NoInfer<Output>>) => Effect<void>;
readonly window: Input;
}) => Effect<Logger<Message, void>, never, Scope>consoleJson
A Logger which outputs logs using a structured format serialized as JSON on a single line and writes them to the console.
Details
For example, console JSON output can render as {"message":["hello"],"level":"INFO","timestamp":"2025-01-03T14:28:57.508Z", "annotations":{"key":"value"},"spans":{"label":0},"fiberId":"#1"}.
Signature
declare const consoleJson: Logger<unknown, void>;consoleLogFmt
A Logger which outputs logs using the [logfmt](https://brandur.org/logfmt) style and writes them to the console.
Details
For example, a console logfmt entry is rendered as timestamp=2025-01-03T14:22:47.570Z level=INFO fiber=#1 message=info.
Signature
declare const consoleLogFmt: Logger<unknown, void>;consolePretty
A Logger which outputs logs in a "pretty" format and writes them to the console.
Details
For example, pretty output can render as [09:37:17.579] INFO (#1) label=0ms: hello followed by an annotation line such as key: value.
Signature
declare const consolePretty: (options?: {
readonly colors?: "auto" | boolean;
readonly formatDate?: (date: Date) => string;
readonly mode?: "browser" | "tty" | "auto";
readonly stderr?: boolean;
}) => Logger<unknown, void>;consoleStructured
A Logger which outputs logs using a structured format and writes them to the console.
Details
For example, console structured output can contain message: [ "info", "message" ], level: "INFO", timestamp: "2025-01-03T14:25:39.666Z", annotations: { key: "value" }, spans: { label: 0 }, and fiberId: "#1".
Signature
declare const consoleStructured: Logger<unknown, void>;defaultLogger
The default logging implementation used by the Effect runtime.
Signature
declare const defaultLogger: Logger<unknown, void>;formatJson
A Logger which outputs logs using a structured format serialized as JSON on a single line.
Details
For example, a JSON entry can render as {"message":["hello"],"level":"INFO", "timestamp":"2025-01-03T14:28:57.508Z","annotations":{"key":"value"}, "spans":{"label":0},"fiberId":"#1"}.
Signature
declare const formatJson: Logger<unknown, string>;formatLogFmt
A Logger which outputs logs using the [logfmt](https://brandur.org/logfmt) style.
Details
For example, a logfmt entry is rendered as timestamp=2025-01-03T14:22:47.570Z level=INFO fiber=#1 message=hello.
Signature
declare const formatLogFmt: Logger<unknown, string>;formatSimple
A Logger which outputs logs as a string.
Details
For example, a simple log entry is rendered as timestamp=2025-01-03T14:22:47.570Z level=INFO fiber=#1 message=hello.
Signature
declare const formatSimple: Logger<unknown, string>;formatStructured
A Logger which outputs logs using a structured format.
Details
For example, a structured entry can contain message: [ "hello" ], level: "INFO", timestamp: "2025-01-03T14:25:39.666Z", annotations: { key: "value" }, spans: { label: 0 }, and fiberId: "#1".
Signature
declare const formatStructured: Logger<
unknown,
{
readonly annotations: Record<string, unknown>;
readonly cause: string | undefined;
readonly fiberId: string;
readonly level: string;
readonly message: unknown;
readonly spans: Record<string, number>;
readonly timestamp: string;
}
>;Creates a new Logger from a log function.
Details
The log function receives an options object containing the message, log level, cause, fiber information, and timestamp, and should return the desired output.
Signature
declare const make: <Message, Output>(
log: (options: Options<Message>) => Output,
) => Logger<Message, Output>;tracerLogger
A Logger which includes log messages as tracer span events.
Details
This logger integrates logging with distributed tracing by recording all log messages as events on the current trace span, making them visible in tracing tools like OpenTelemetry, Jaeger, or Zipkin.
This logger is included in the default set of loggers for all Effect programs, so log messages automatically appear as span events unless you override the default loggers.
Signature
declare const tracerLogger: Logger<unknown, void>;Guards
Layers
Creates a Layer which will overwrite the current set of loggers with the specified array of loggers.
Details
If the specified array of loggers should be _merged_ with the current set of loggers (instead of overwriting them), set mergeWithExisting to true.
Signature
declare function layer<Loggers extends readonly Array<Logger<unknown, unknown> | Effect<Logger<unknown, unknown>, any, any>>>(loggers: Loggers, options?: {
readonly mergeWithExisting?: boolean;
}): Layer<never, Loggers extends readonly [] ? never : Error<Loggers[number]>, Exclude<Loggers extends readonly [] ? never : Services<Loggers[number]>, Scope>>Logging
Creates a scoped logger that writes string logger output to a file.
Details
The returned effect requires FileSystem and Scope. The file logger batches string output, writes each batch to the specified path, and flushes remaining entries when the scope closes.
Signature
declare const toFile: (path: string, options?: {
readonly batchWindow?: Input;
readonly flag?: OpenFlag;
readonly mode?: number;
}) => <Message>(self: Logger<Message, string>) => Effect<Logger<Message, void>, PlatformError, Scope | FileSystem> & <Message>(self: Logger<Message, string>, path: string, options?: {
readonly batchWindow?: Input;
readonly flag?: OpenFlag;
readonly mode?: number;
}) => Effect<Logger<Message, void>, PlatformError, Scope | FileSystem>withConsoleError
Returns a new Logger that writes all output of the specified Logger to the console using console.error.
When to use
Use when logger output should be routed to console.error, such as error logs that should appear on stderr instead of stdout.
Signature
declare function withConsoleError<Message, Output>(
self: Logger<Message, Output>,
): Logger<Message, void>;withConsoleLog
Returns a new Logger that writes all output of the specified Logger to the console using console.log.
When to use
Use when a logger's string or object output should be routed to console.log for development or debugging.
Signature
declare function withConsoleLog<Message, Output>(
self: Logger<Message, Output>,
): Logger<Message, void>;withLeveledConsole
Returns a new Logger that writes all output of the specified Logger to the console.
Details
Will use the appropriate console method (i.e. console.log, console.error, etc.) based upon the current LogLevel.
Debug uses console.debug, Info uses console.info, Trace uses console.trace, Warn uses console.warn, Error and Fatal use console.error, and all other levels use console.log.
Signature
declare function withLeveledConsole<Message, Output>(
self: Logger<Message, Output>,
): Logger<Message, void>;Mapping
Transforms the output of a Logger using the provided function.
When to use
Use when an existing logger's output should be transformed without recreating the logging logic.
Signature
declare const map: <Output, Output2>(f: (output: Output) => Output2) => <Message>(self: Logger<Message, Output>) => Logger<Message, Output2> & <Message, Output, Output2>(self: Logger<Message, Output>, f: (output: Output) => Output2) => Logger<Message, Output2>Models
A logger that transforms a runtime log event into an output value.
Details
The runtime calls log with the message, level, cause, fiber, and timestamp for each log event. Use Logger.layer to install one or more loggers for an effect.
Signature
interface Logger<in Message, out Output> extends Pipeable {
readonly "~effect/Logger": "~effect/Logger";
log(options: Options<Message>): Output;
}Options
Information supplied to a Logger for a single log event.
Details
Includes the logged message, log level, cause, current fiber, and timestamp.
Signature
interface Options<out Message> {
readonly cause: Cause<unknown>;
readonly date: Date;
readonly fiber: Fiber<unknown, unknown>;
readonly logLevel: LogLevel;
readonly message: Message;
}Services
CurrentLoggers
Context reference containing the active loggers for the current fiber.
Details
By default this set includes the default logger and the tracer logger. Providing Logger.layer replaces or merges with this set depending on its options.
Signature
declare const CurrentLoggers: Context.Reference<ReadonlySet<Logger<unknown, any>>>;LogToStderr
Context reference that routes the built-in default logger and TTY pretty console logger to stderr.
When to use
Use to route built-in logger output to stderr while keeping stdout reserved for protocol messages or data output.
Details
The reference defaults to false. Providing true makes the affected loggers call console.error instead of console.log.
See
defaultLoggerfor the runtime logger affected by this referenceconsolePrettyfor the TTY-mode pretty console logger affected by this referencewithConsoleErrorfor routing a specific formatter logger toconsole.error
Signature
declare const LogToStderr: Context.Reference<boolean>;
Creates a scoped logger that batches the output of another logger.
Details
The returned effect starts a scoped background process that periodically passes buffered outputs to
flush. When the scope closes, the background process is interrupted and any remaining buffered entries are flushed.