Using the `debug` module to avoid polluting your application logs with logs from Node modules
Tags: node, javascript
Published: 2020-03-26 22:50:09

---
title: Using the `debug` module to avoid polluting your application logs with logs from Node modules
published: true
canonical_url: https://www.coreycleary.me/using-the-debug-module-to-avoid-polluting-your-application-logs-with-logs-from-node-modules/
tags: node,javascript
---

Have you ever added logging to your custom Node modules, thinking you'll benefit from all that extra information, only to find that when you add the modules as dependencies, run <code>npm install</code> and <code>npm start</code>, your application logs start looking like the below?

<img class="aligncenter size-full wp-image-629" src="https://www.coreycleary.me/wp-content/uploads/2018/07/Screen-Shot-2018-07-10-at-6.19.59-PM.png" alt="" width="654" height="426">

How were you able to find any of the <em>application</em> information you actually needed? Information like which users logged in and when they logged in, and not log info coming from your application's dependencies:

<img class="aligncenter size-full wp-image-631" src="https://www.coreycleary.me/wp-content/uploads/2018/07/Screen-Shot-2018-07-10-at-6.19.59-PM-1.png" alt="" width="654" height="426">

Similarly, have you ever been in a war room scenario at work when you suspected production was down due to a change your team made in a Node module dependency, but the only logs you had to troubleshoot looked like:

<img src="https://www.coreycleary.me/wp-content/uploads/2018/07/Screen-Shot-2018-07-10-at-6.24.53-PM.png" alt="" width="754" height="51" class="aligncenter size-full wp-image-633">

This is what log pollution looks like from a bird’s eye view:

<img src="https://www.coreycleary.me/wp-content/uploads/2018/07/logging-node-module.png" alt="" width="486" height="350" class="aligncenter size-full wp-image-635">
<h3>What do we want</h3>
The dream logging scenario is being able to keep your module logs out of your application/service logging, but being able to turn them on for troubleshooting purposes when you need to.

To achieve this, I'm going to show you how you can use the <a href="https://github.com/visionmedia/debug" target="_blank" rel="noopener">debug</a> module to toggle on/off logs in your Node modules.

<em>OFF</em> for when you don't need them, and your service that consumes the module is running fine.
<em>ON</em> for when you're facing issues and need as much logging information as you can get.
<h3>Overview of the `debug` module</h3>
Functionality-wise, think of the debug module not in the way you'd usually think of as a debugger - like the kind you'd set breakpoints with in your IDE - but think of it more like a modified <code>console</code> module. One that lets you turn on and off your logs depending on what you need. If you clicked the link to the GitHub page, you might have encountered various other features it has, like namespacing for example. Don't worry about those for now, just know it's a tool to save you in production (and lower environments too).
<h3>Implementing `debug` in Node modules you wrote yourself</h3>
Let's look at an example of using <code>debug</code> in code. Imagine the below is a module:
```javascript
const debug = require('debug');
const log = debug('http:server');
const http = require('http');
const name = 'Demo App for debug module';

log('booting %o', name);

http.createServer((req, res) => {
  log(req.method + ' ' + req.url);
  res.end('debug example\n');
}).listen(3200, () => {
  log('listening');
});
```
Implementing <code>debug</code> is pretty easy. All we have to do is import/require the module then create a logger - <code>const log = debug('http:server');</code>. What is that 'http:server'? It's simply the flag/namespace for that specific logger that you will pass to the <code>DEBUG</code> environment variable in order to turn <b>ON</b> the debugging.

When you start your application - the one that's importing this module - you will start it like so:

<code>DEBUG=http:server node app-entrypoint.js</code>

What if we want separate loggers in order to toggle some logs but not others? For example, what if we want to toggle only errors? It's as simple as creating another logger, like so:
```javascript
const debug = require('debug');
const log = debug('http:server');
const errorLogger = debug('http:error'); // create new logger here, passing it a new namespace
const http = require('http');
const name = 'Demo App for debug module';

log('booting %o', name);

http.createServer((req, res) => {
  log(req.method + ' ' + req.url);
  res.end('hello\n');

  // fake an error to demonstrate using debug for http:error namespace
  setTimeout(() => {
    errorLogger('fake error'); // then call the logger 
  }, 1000);
}).listen(3200, () => {
  log('listening');
});
```
So turning on only errors would look like:

<code>DEBUG=http:error node app-entrypoint.js</code>

And when you want to log all namespaces (in this case, <code>http:server</code> and <code>http:error</code>), simply pass the wildcard <code>*</code> flag.

<code>DEBUG=http:* node app-entrypoint.js</code>

Let's see what those logs look like now:
<img class="aligncenter size-full wp-image-616" src="https://www.coreycleary.me/wp-content/uploads/2018/07/Screen-Shot-2018-07-10-at-7.33.54-AM.png" alt="" width="1407" height="179">
Then, when we load the page:
<img class="aligncenter size-full wp-image-617" src="https://www.coreycleary.me/wp-content/uploads/2018/07/Screen-Shot-2018-07-10-at-7.34.03-AM.png" alt="" width="1414" height="217">

<em>As a heads-up, <code>debug</code> writes to <code>stderr</code>, not <code>stdout</code>, so <a href="https://www.coreycleary.me/why-should-your-node-js-application-not-handle-log-routing/" target="_blank" rel="noopener">if you have a log router that picks up logs based on different sources</a>, be aware these debug logs will end up in the stderr stream.</em>

Lastly, you'll also have a choice to make:
<ul>
 	<li>you can log everything you're going to log in the modules you've written using `debug`</li>
 	<li>OR you can still log some things using `console.log()` / `console.error()` and others to `debug`</li>
</ul>
If you have mandatory things that absolutely need to be logged - and that matter to the application that's using the module - log those with <code>console</code>. But if you don't, I'd log everything using <code>debug</code>.
<h3>Turning on `debug` for third-party modules</h3>
So far what we've covered is great if you (or your team) wrote the module.

<em>But what if you're using a third-party module that you need to turn on debugging for?</em>

Maybe you've done troubleshooting for every part of your application, now thinking that it might be that open-source module you're using that is causing you issues.

The good news is that <code>debug</code> is such a widely used module, that many modules in npm are probably using it. Third-party module creators know (or at least, <em>should know</em>) that users of that module don't really want it's logs on by default, for all the cluttering up of the rest of the logs that can happen.

<a href="https://expressjs.com/en/guide/debugging.html" target="_blank" rel="noopener">Express uses the debug module internally</a> so if you're using Express and need to troubleshoot it, you can turn on the logs by running:

<code>DEBUG=express:* node your-app-entrypoint.js</code>
<h3>Finding if and how an open-source Node module uses `debug`</h3>
<em>What if the module hasn't documented if it's using <code>debug</code> or not?</em> Again, chances are that it's being used, but you'll have to do some digging.

We already know Express documents how to use it, but let's assume that it wasn't documented:

First, you could search the project's GitHub (or other open source site) for its <code>package.json</code> and look for the module listed there as a dependency:

<img class="aligncenter size-full wp-image-625" src="https://www.coreycleary.me/wp-content/uploads/2018/07/Screen-Shot-2018-07-10-at-7.52.55-AM-1.png" alt="" width="563" height="279">

Once that's confirmed, you'll also need to confirm 1) it's actually being used and 2) what flags it takes for toggling. GitHub has a nice feature now where you can use the search bar to search the project itself. If we search "debug" in the Express project, we'll find <a href="https://github.com/expressjs/express/search?q=debug&amp;unscoped_q=debug" target="_blank" rel="noopener">the following</a>:

<img class="aligncenter size-full wp-image-609" src="https://www.coreycleary.me/wp-content/uploads/2018/07/Screen-Shot-2018-07-09-at-7.55.35-PM.png" alt="" width="834" height="459">

We can see that the toggle flag is "express", so "express:*" would give us the logs for <b>everything</b>, "express:view" would give us the logs for the views, etc.
<h3>Wrapping up</h3>
Hopefully you see how easy it is to implement <code>debug</code> in your Node modules and turn it on for third-party modules, as well as how much it can help clean up your logs while giving you an easy way to turn them back on for troubleshooting.

Love JavaScript but still getting tripped up by how you should build production-level apps? I publish articles on JavaScript and Node every 1-2 weeks, so if you want to receive all new articles directly to your inbox, <a href="https://www.coreycleary.me/about/">here's the link</a> to subscribe to my newsletter!