Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท util, assert and the Test Runner

Node.js util.debuglog() function

Reference for util.debuglog() in Node.js: create a logger that prints to stderr only when NODE_DEBUG names its section, with wildcards and the enabled flag.

util.debuglog(section) returns a logging function that writes to standard error only when the NODE_DEBUG environment variable lists that section. When the variable is not set, the function does almost nothing, so you can leave debug statements in a library without slowing it down or cluttering normal output.

Node itself uses this for internals such as NODE_DEBUG=http or NODE_DEBUG=fs. Your own code can use the same mechanism with sections you name yourself, which gives users of a library one familiar switch to turn tracing on.

NODE
import { debuglog } from "node:util";

const debug = debuglog("myapp");
debug("connected to %s", "db"); // printed only with NODE_DEBUG=myapp

Try it

Node.js Off by default, on with NODE_DEBUG

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js The optional callback and the enabled flag

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
util.debuglog(section: string, callback?: (logger: Function) => void): Function & { enabled: boolean }
Name Description
section Name of the logger, compared case-insensitively with the entries of NODE_DEBUG.
callback Optional. Called the first time the logger is used with the real logging function, handy for a lazy initialization.

Returns: a function that works like console.log() formatting (%s, %d, %j, %o) and prefixes each line with the upper-cased section and the process id, for example DEMO 1234: hello. The function has an enabled property that is true when the section is active.

Usage notes

  • NODE_DEBUG is a comma-separated list: NODE_DEBUG=http,fs. A trailing * is a wildcard, so NODE_DEBUG=my* enables myapp and mylib.
  • The variable is read at startup. Changing process.env.NODE_DEBUG inside a running program has no effect on loggers.
  • Output goes to stderr, never stdout, so it does not corrupt data piped from your program.
  • Arguments are evaluated even when logging is off. Wrap expensive work in if (debug.enabled).
  • The process id in every line changes between runs; mask it when you compare outputs.
  • Pick a section name that is unlikely to clash with Node's own (http, net, fs, stream...). Prefix it with your package name.
  • For richer tracing with levels and timestamps use a logging library, or diagnostics_channel for structured events.