Skip to content

JSON File Channel

JSONFileLog is a drop-in replacement for FileLog that writes structured JSON instead of plain text. Every entry is a typed object — no regex parsing at query time.

import { JSONFileLog } from "@warlock.js/logger";
const channel = new JSONFileLog({
storagePath: process.cwd() + "/storage/logs",
chunk: "daily",
});

The extension is json (or jsonl with format: "jsonl"), regardless of the extension option. By default each file is a JSON object with a messages array:

{
"messages": [
{
"content": "New user created",
"level": "info",
"date": "15-03-2024 10:22:01",
"module": "users",
"action": "register"
},
{
"content": "Card declined",
"level": "error",
"date": "15-03-2024 10:22:03",
"module": "payments",
"action": "charge",
"stack": [
"Error: Card declined",
" at chargeCard (/app/src/payments.ts:42:11)",
" at processTicksAndRejections (node:internal/process/task_queues:95:5)"
]
}
]
}

With the default format: "json", every write reads the whole file, adds the new entries and writes it back, so a write gets slower as the file grows (up to maxFileSize, 10 MB by default). format: "jsonl" writes one JSON object per line to a .jsonl file and only appends, so each write costs the same however large the file is:

storage/logs/2026-11-12.jsonl
new JSONFileLog({ chunk: "daily", format: "jsonl" });
// {"content":"New user created","level":"info","date":"12-11-2026 10:22:01","module":"users","action":"register","timestamp":"..."}

Each line holds the same fields as an entry of the messages array. Default: "json".

When an existing .json file cannot be parsed (for example a write cut short by a crash), it is never overwritten: it is renamed to <file>.json.corrupt-<epoch ms> next to it, a new file is started, and the logger’s onChannelError handler is told where the old file went.

AspectFileLogJSONFileLog
Output formatPlain-text linesJSON object with messages array
Error stackRaw multi-line string after [trace]Split on newlines, stored as string[] in stack
Message fieldPre-formatted log linecontent field holds the original string
File extensionConfigurable (default "log")"json", or "jsonl" with format: "jsonl"

It inherits every FileLog option and supports the same chunking, rotation, and groupBy features.

JSONFileLog writes through safe-stable-stringify (the same library Pino and Winston use), so the context payload can carry shapes that would otherwise throw in JSON.stringify:

ShapeSerialized as
Circular referencehandled (no throw)
BigIntstringified value
Function / symboldropped (standard JSON behavior)
Error (top-level or nested in context){ name, message, stack, ...enumerableProps }
Class instanceenumerable own properties — same as default JSON

The channel does not tag class instances with their class name. If you need a specific shape, pre-shape the value before passing it to context:

log.error("orders", "checkout", "Card declined", {
order: { id: order.id, status: order.status }, // not the full Order instance
declineReason,
});