Getting Started With morgan: the Node.js Logger Middleware

While this tutorial has content that we believe is of great benefit to our community, we have not yet tested or edited it to ensure you have an error-free learning experience. It's on our list, and we're working on it! You can help us out by using the "report an issue" button at the bottom of the tutorial.

morgan is a great logging tool that anyone who works with HTTP servers in Node.js should learn to use. morgan is a middleware that allows us to easily log requests, errors, and more to the console. It’s easy to use, but still powerful and customizable.

Getting Set Up

We need to add morgan to our project’s dependencies. We’ll be using npm, but feel free to use Yarn. This assumes you’ve already initialized an npm project in your working directory.

$ npm install morgan --save

Now that we’ve added morgan to our project, let’s require it.

const morgan = require('morgan');

For simplicity’s sake, our example is going to use an Express server, but morgan also works with the built-in Node.js http module.

const express = require('express');
const morgan = require('morgan');

const app = express();

app.listen(3000, () => {
    console.debug('App listening on :3000');

Great, our Express server is setup, now let’s add some request logging!

Predefined format strings

morgan comes with a suite of presets, which are plug-and-play. To use these, we do this: morgan('tiny') In this case, tiny is the name of the predefined format string that we’re using.

Using morgan with Express

Since morgan is a middleware, using it with something like Express is really easy. All we have to do is this:

const app = express();

app.use(morgan(/* format string here */));

Format Strings

The template strings that morgan uses are called format strings. A format string might look something like this.

:method :url :status :res[content-length] - :response-time ms


Tokens are the keywords following the :’s. Tokens are defined as functions. We’ll look at making custom tokens next.

Creating Our Own Tokens

One of the great things morgan allows us to do is make our own tokens. It’s incredibly useful, versatile and easy to do. All we have to do is call morgan.token(name, function).

The first argument we pass-in is the name of the token. If I do morgan.token('my-token', ...);, for example, I would call that token using :my-token.

The second argument is a callback function. morgan will run this each time it logs something using the token. morgan will pass two parameters to the function: req and res. Let’s create a token that displays the domain that the request was sent through.

morgan.token('host', function(req, res) {
    return req.hostname;

Using our custom tokens

Using the token we just made is easy. Just call the token like we would any other token.

morgan(':method :host :status :res[content-length] - :response-time ms'); // This is a modified version of morgan's tiny predefined format string.

Creating Custom Tokens with Custom Arguments

You’ve probably noticed that brackets ([ ]) have showed up a few times in our format strings following tokens. Square brackets denote arguments to be passed to a token. We can make our tokens accepts additional arguments. Let’s create a token that grabs one of the parameters from the request.

morgan.token('param', function(req, res, param) {
    return req.params[param];

And to use it:

morgan(':method :host :status :param[id] :res[content-length] - :response-time ms');

Using morgan with the Built-In http Module

Using morgan with the Node.js built-in http module is easy as well. Here’s an example from the morgan docs.

We’re done, yay! That’s all we’re going to cover in this article, but I recommend you checkout the morgan documentation. Stay tuned, we might have more morgan articles coming soon too! Thanks for reading!

Creative Commons License