Node.js / Express middleware

In this tutorial, we’ll start analysing the web traffic on a Node/Express application using Hyperwatch.

We’ll use the Websocket protocol that is one of the many protocol available with the Hyperwatch Express Logger middleware.

Let’s start!

Install Hyperwatch

On the same server where the Node/Express application is running, or on a server that is reachable by it, install the Hyperwatch processor.

As a prerequisite, you’ll need Node.js >= 24. We recommend nvm.

nvm install 24

Install from npm

npm install -g @hyperwatch/hyperwatch

Install from Git

Alternatively, for development purpose, you can use Git and clone the public repository:

git clone https://github.com/hyperwatch/hyperwatch.git
cd hyperwatch
npm install

Configure Hyperwatch

In our suggested configuration, Hyperwatch will be listening for access logs using the Websocket protocol.

All communications between your Node/Express application and Hyperwatch will be happening in clear, please only use that setup on your internal network. If on the public internet, we’re advising to use the Websocket Secure protocol (wss) which is straightforward but out of the scope of this tutorial.

Now, you can create your own configuration in express_websocket_example.js (a complete version is available in config/express_websocket_example.js):

module.exports = function (hyperwatch) {
  const { pipeline, input } = hyperwatch;

  hyperwatch.init();

  const webSocketServerInput = input.websocket.create({
    name: 'WebSocket server (JSON standard format)',
    type: 'server',
    path: '/input/log',
  });

  pipeline.registerInput(webSocketServerInput);
};

Configure Node/Express

Now, install the Hyperwatch Express Logger middleware in your Node application:

npm install --save @hyperwatch/express-logger

Then simply configure it like any other middlewares:

const express = require('express');
const hyperwatchExpressLogger = require('@hyperwatch/express-logger');

const app = express();

app.use(hyperwatchExpressLogger('websocket', 'ws://localhost:3000/input/log'));

In this example, there are 3 important things:

1. If Hyperwatch is running on the same server, we can use localhost as IP address. If it’s on a different server, replace localhost by the proper private or public IP address.
2. Replace the port (here 3000) by the relevant one, it should be the main port where Hyperwatch is running.
3. Finally, the path /input/log should match the one configured on Hyperwatch side, If you’re following this tutorial from start to end, nothing to change!

Now, that you added and configured the Hyperwatch middleware, you can deploy and restart your application.

Note: The Hyperwatch middleware is also capable of logging using the HTTP(s) or the Syslog protocol. If you have any trouble with Websocket, you might want to try these one.

Start Hyperwatch

Ok, now go back to where you wrote the config.

hyperwatch express_websocket_example.js

Browse the interface

Now, you can point your browser to the /status page on the IP/port where Hyperwatch is running (e.g. http://localhost:3000/status). If you see traffic going through your input, congrats you made it!

To watch the logs live at /logs/main and explore aggregations such as /addresses or /identities, activate the corresponding modules. See Global Configuration.