DEV Community

Cover image for What is the DEBUG ๐Ÿ› environment variable in Node.js, and how to use it?
aderchox
aderchox

Posted on • Updated on

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
Enter fullscreen mode Exit fullscreen mode

For example, in Express, you might see:

DEBUG=express:* node index.js
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

DEBUG=express:application node index.js
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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');
Enter fullscreen mode Exit fullscreen mode

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');
});
Enter fullscreen mode Exit fullscreen mode

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

DEBUG=http:server node app.js
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)