Module: utils/logFormatter

Centralised log formatting with .env-driven configuration.

Environment variables

Variable Default Description
LOG_LEVEL "info" Minimum severity: debug / info / warn / error
LOG_DATE_FORMAT "iso" Timestamp format: iso / utc / local / epoch
LOG_TIMEZONE system IANA timezone for local format
LOG_JSON "false" "true" to emit structured JSON lines

Exports

  • formatTimestamp — Produce a formatted timestamp string.
  • formatLogLine — Format a complete log line for stdout.
  • shouldLog — Check if a level should be printed.
  • LOG_LEVEL — Configured minimum log level (numeric).
Source:

Methods

(static) formatLogLine(level, runId, msg) → {string}

Format a complete log line for server stdout.

When LOG_JSON=true, emits a single-line JSON object: {"ts":"...","level":"info","runId":"RUN-42","msg":"Starting crawl"}

Otherwise emits the human-readable format: [2025-04-03T12:34:56.789Z] [INFO] [RUN-42] Starting crawl

Parameters:
Name Type Description
level "debug" | "info" | "warn" | "error"
runId string
msg string
Source:
Returns:
Type
string

(static) formatTimestamp(dateopt) → {string}

Produce a formatted timestamp string according to LOG_DATE_FORMAT.

Parameters:
Name Type Attributes Description
date Date <optional>

— defaults to now
Source:
Returns:
Type
string

(static) shouldLog(level)

Returns true if the given level should be printed based on LOG_LEVEL.

Parameters:
Name Type Description
level "debug" | "info" | "warn" | "error"
Source:

(static) structuredLog(event, propsopt)

Emit a structured lifecycle event to stdout.

When LOG_JSON=true, emits a JSON line with the event name and all props: {"ts":"...","event":"run.start","runId":"RUN-42","tests":5}

When LOG_JSON=false, emits a human-readable line: [2025-04-03T12:34:56.789Z] [EVENT] run.start runId=RUN-42 tests=5

Use this for machine-filterable lifecycle events (run start/end, browser launch, pipeline stage transitions). Use formatLogLine() for free-form human-readable messages.

Parameters:
Name Type Attributes Description
event string

— semantic event name (e.g. "run.start", "browser.launched")
props Object <optional>

— structured key-value pairs to include
Source: