When the logs are silent — log4js stopped writing log entries after upgrade

log4js 2.x doesn’t write logs by default, here’s how to configure it explicitly

We love to use log4js in our node applications, for its nicely formatted log output and ease of configuration. But a couple of days ago, after updating the dependencies of one of our node projects to their latest version, two things happened:

• VSCode started complaining that the logs configuration must have property "appenders" of type object
• In production, the application stopped showing logs altogether — it looked like nothing was happening.

Turns out, there was a major change in log4js we hadn’t noticed! Here’s what we did to restore our precious logs.

Get VSCode to stop complaining

VSCode is set up to work with log4js through an external configuration file we provide to our application via the environment variable LOG4JS_CONFIG as specified in the API documentation.

Our launch configuration for the application looks like this:

{
    "type": "node",
    "request": "launch",
    "name": "Run application",
    "program": "${workspaceRoot}/index.js",
    "env": {
        "LOG4JS_CONFIG": "${workspaceRoot}/.vscode/log4js.json"
    }
}

Where the file .vscode/log4js.json contains the logs configuration. Up until log4js v1.1.1 the configuration file was needed only to tell VSCode to print the logs in the standard output console, and it looked something like this:

{
    "appenders": [
        { "type": "console" }
    ],
    "replaceConsole": true
}

In v2.* the configuration format has changed to:

{
    "appenders": {
        "out": { "type": "console" }
    },
    "categories": {
        "default": {
            "appenders": [ "out" ],
            "level": "debug"
        }
    }
}

Where both appenders and level are required parameters inside the categories.default object.

So far, nothing has changed in the source code of the application, and we can go back to running it smoothly through VSCode.

Bring logs back in production

Once the logs disappeared in production, we quickly realized that this was the case when executing the application in any environment outside VSCode (e.g. from the command line on the local machine).

Reading through the new release documentation, we figured out that this was on purpose.

By default, log4js will not output any logs (so that it can safely be used in libraries). The level for the default category is set to OFF. To enable logs, set the level […]

At this point, we have two choices:

1. Change the code of the application to what the documentation suggests
2. Use an external configuration file, setting the LOG4JS_CONFIG variable

Changing the code is as simple as going from what we had before:

const logger = require('log4js').getLogger();
logger.debug('Some debug messages');

to:

const logger = require('log4js').getLogger();
logger.level = 'debug';
logger.debug('Some debug messages');

However, adding the external configuration file has the added advantage of flexibility between environments:

• we can keep different configuration files available locally, dependently on what we are doing (dry-running the application, debugging it, …)
• we can create configuration files more suitable for production (that can be, for example, directly provided to the application by the orchestrating service)

Ultimately, we decided to make it a best practice to always provide a configuration to our services through the LOG4JS_CONFIG variable, much like the one that we define inside VSCode.

And with this, logging was restored to its full capability!

Happy coding :)

Photo: Jonh Bugg