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.
import { debuglog } from "node:util"; const debug = debuglog("myapp"); debug("connected to %s", "db"); // printed only with NODE_DEBUG=myapp
Try it
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.
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
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_DEBUGis a comma-separated list:NODE_DEBUG=http,fs. A trailing*is a wildcard, soNODE_DEBUG=my*enablesmyappandmylib.- The variable is read at startup. Changing
process.env.NODE_DEBUGinside 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_channelfor structured events.