What is the DEBUG 🐛 environment variable in Node.js, and how to use it?

_{(The credit for the cover image goes to coralogix)}

You might have seen a command like this while navigating in Node.js projects:

$ DEBUG=myapp:* npm start

For example, in Express, you might see:

DEBUG=express:* node index.js

So what is it?

Although it's used by Express, it's indeed more broadly, the way a popular NPM package called debug works, which is used internally in Express too. Under the hood, the debug package expects the DEBUG environment variable to determine what debug messages to print (could be on the console, or into a file, or into stdout to be collected by a log aggregator service).

In case of Express specifically, to see all the internal logs used in it, we could set the DEBUG environment variable to express:* when launching the app. E.g., on Linux, run:

DEBUG=express:* node index.js

Or to see logs only from the application implementation, run:

DEBUG=express:application node index.js

The syntax used in both of the above commands (FOO=bar command) is the general Linux-y way of defining a one-off environment variable exclusive to only a single execution of a command, i.e., will only be accessible to the command and only at that single time. It's very beneficial that it's a one-off thing, as it won't pollute the environment variables' global space unnecessarily).

debug is like an augmented version of console.log, but unlike console.log, we don’t have to comment out debug logs in production code. Instead, logging is turned off by default and can be conditionally turned on by using the DEBUG environment variable.

You can also specify more than one debug namespace (whether regarding Express, or regarding any other modules by assigning a comma-separated list of names:

DEBUG=http,mail,express:* node index.js

If you wonder what a "namespace" is, it's again related to the debug package, for example, consider this snippet:

const debug = require('debug');
const httpServerLog = debug('http:server');

What is that 'http:server'? It's simply the flag/namespace for that specific logger that you will pass to the DEBUG environment variable in order to turn ON the debugging. So now you could do:

const http = require('http');
http.createServer((req, res) => {
  httpServerLog(req.method + ' ' + req.url);
  res.end('debug example');
}).listen(3200, () => {
  httpServerLog('listening');
});

And to enable the above logs, the "http:server" namespace has to be enabled, so we'll do:

DEBUG=http:server node app.js

You could check the package.json of any 3rd-party packages to see if they've used the debug module or not, and if they have, you could check the namespaces they've defined and pass them using the same method (of passing the DEBUG environment variable to pass the desired namespaces) to see their logs.

Read more about the "debug" package here and here.

Hey, you're also invited to join our small and fledging 🐥🐣 Discord community called TIL (stands for "Today-I-Learned") where we share things that we learn with each other, in the realm of web programming, using this link.

Thanks for reading this article 👋 You're very welcome to suggest any fixes or improvements in the comments section below.