Skip to content

Channel configurations

Every built-in channel extends BasicLogConfigurations (the shared options — levels, dateFormat, filter, context, redact; see Types) and adds its own fields.

ConsoleLog options — BasicLogConfigurations plus:

OptionTypeDefaultDescription
showContextbooleanfalseRender the entry’s context on a second line via util.inspect. When false, context is dropped from console output (file/JSON channels still keep it).
contextDepthnumber4Depth passed to util.inspect when rendering context. Only applies when showContext is enabled.
minLevelLogLevelnoneLowest severity this channel prints (debug < info = success < warn < error < fatal). Other channels are not affected.

FileLog options — BasicLogConfigurations plus:

OptionTypeDefaultDescription
storagePathstringprocess.cwd() + "/storage/logs"Directory where log files are stored. Created automatically.
namestring"app"File name of a single chunk (without extension) and the {name} token.
chunk"single" | "daily" | "hourly""single"How entries split across files.
rotatebooleantrueRotate the file when it exceeds maxFileSize.
extensionstring"log"File extension. Ignored by JSONFileLog (always "json").
fileNamestring | (date: Date) => stringby chunkFile name pattern ({YYYY} {MM} {DD} {HH} {mm} {name}) or function; replaces the chunk’s default (name, {YYYY}-{MM}-{DD}, {YYYY}-{MM}-{DD}-{HH}).
rotateFileNamestring | (date: Date) => string"{YYYY}-{MM}-{DD}"Middle part of a rotated file’s name (<file name>-<rotateFileName>-<epoch ms>.<extension>); same forms as fileName.
retention{ maxFiles?: number; maxAgeDays?: number; match?: RegExp }noneRemove this channel’s old files on boot and when a new file starts. See File Channel → Retention.
maxFileSizenumber10485760 (10 MB)Max bytes before rotation. Only checked when rotate is true.
maxMessagesToWritenumber100Messages held in the in-memory buffer before flushing. Also flushed every 5 seconds.
groupBy("level" | "module" | "action")[]noneArrange files into a subdirectory hierarchy. Order = nesting depth.
maxBufferedMessagesnumber10000Entries kept in memory while writes keep failing; past it the oldest are dropped and one notice is reported. Infinity keeps everything.
escapebooleantrueWrite line breaks, tabs and control characters in messages as visible escapes so each entry is one line. false keeps line breaks raw; terminal escapes are still removed.

FileLogConfig also re-declares levels and dateFormat from the shared base, so they’re available alongside the file-specific options.

JSONFileLog extends FileLog — it accepts the entire FileLogConfig shape and behaves identically for chunking, rotation, buffering, and groupBy. The one override: extension is forced to "json" ("jsonl" with format: "jsonl") regardless of what you pass. Its config type is JSONFileLogConfig, which adds:

OptionTypeDefaultDescription
format"json" | "jsonl""json""json": one { messages: [...] } document per file. "jsonl": one JSON object per line, append-only writes.

See JSON File Channel for the output-format differences.

SentryLog options — BasicLogConfigurations plus:

OptionTypeDefaultDescription
clientSentry namespace / forwarder—Reuse an already-initialized Sentry instance (e.g. the @sentry/node namespace).
optionsSentryInitOptions—Sentry init options (mirrors @sentry/node’s NodeOptions), used when the channel owns initialization.
eventLevelsLogLevel[]["error", "warn"]Levels delivered as Sentry events; every other level becomes a breadcrumb.
flushTimeoutnumber2000Milliseconds flush() waits for the Sentry transport to drain on shutdown.

@sentry/node is an optional peer — install it only when using this channel. See Sentry channel.