Node.js Reference ยท CLI Flags
Node.js NODE_DEBUG environment variable
Reference for NODE_DEBUG: turn on internal debug output for core modules such as http, net, fs and module, and add your own channels with util.debuglog().
NODE_DEBUG is a comma-separated list of debug channels. When a channel is listed, Node writes its internal diagnostic messages to standard error. Core modules define channels with names such as http, net, tls, stream, fs, module, child_process, timer and worker. It is a zero-code way to see what the runtime is doing: which module file was loaded, how a socket changed state, why a request was parsed the way it was.
You can create your own channels with util.debuglog(). They cost almost nothing when disabled, so libraries can keep many of them in production code.
// shell: NODE_DEBUG=http,net node server.js
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
// NODE_DEBUG=channel1,channel2 // util.debuglog(section[, onFirstUse]): (msg, ...args) => void (with .enabled) // util.debug is an alias of util.debuglog
| Name | Description |
|---|---|
NODE_DEBUG |
Comma-separated channel names. Matching ignores case. A trailing * matches any channel starting with that prefix. |
section |
The channel name given to util.debuglog(). It is printed in upper case. |
onFirstUse |
Optional callback that receives the logging function the first time it is called when enabled; handy for swapping in a smarter logger. |
Returns: a function that formats like util.format() and writes SECTION pid: message to standard error. The function has a boolean enabled property, so you can skip expensive argument building.
Usage notes
- Output goes to stderr, not stdout, so it does not corrupt piped program output.
- Format:
NAME pid: text. The process id makes lines from worker and child processes distinguishable; strip it when you compare output. - Read once at startup. Changing
process.env.NODE_DEBUGlater does nothing for channels already created. Set it in the shell,NODE_OPTIONS-style wrapper orchild_processenv. - Volume.
http,netandstreamproduce a lot of lines under load. Turn them on for a short reproduction, never as a permanent setting. - Internal format is not an API. The text of core debug messages changes between releases. Use it to investigate, not to parse.
NODE_DEBUG_NATIVEis a separate variable for native C++ categories (for exampleNODE_DEBUG_NATIVE=fs) and is mostly useful when building Node itself.- For your own libraries,
debuglogis the dependency-free alternative to thedebugpackage. Use dotted names (mylib.pool) so a user can enable all withmylib*. - Not the inspector.
NODE_DEBUGprints diagnostics; it does not attach a debugger. See--inspectfor that.