Hyperwatch

Hyperwatch is a flexible access log processor that helps operators analyze HTTP traffic reaching their infrastructure.

Hyperwatch is built on a real-time stream processor handling logs from inputs of any type:

• CDNs (Cloudfront, Cloudflare, Akamai, ...)
• Load Balancers (ELB)
• Reverse Proxies (Nginx, Haproxy, ...)
• Web Servers (Nginx, Apache, ...)
• Applications (Node, Ruby, PHP, ...)

Install

Make sure you have Node.js version >= 24.

We recommend using nvm: nvm install && nvm use.

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

Start

npm start

It's loading the default configuration, it's the same as:

npm start config/default

Configure

The first thing you might want is configuring inputs to connect Hyperwatch to your traffic sources and convert it in the proper format.

In order to do this, you need to create a new configuration file such as config/custom.js.

See Input Configuration for the list of available input types and how to configure them.

Modules (live log streams, User-Agent parsing, GeoIP, aggregations, …) and a few constants are configured with a .hyperwatchrc file. Only the status module is active by default. To learn more, head to Global Configuration.

To tag requests from listed IPs and User-Agents, and sync those lists with Cloudflare custom rules, see Firewall.

Start with custom configuration

npm start config/custom

The Hyperwatch API and WebSocket will be served from port 3000 by default. Open http://localhost:3000/ to check the status of your inputs. The top navigation links to the addresses, identities and logs pages of the active modules, and to /pipeline, which shows how the pipeline is set up: inputs, nodes, and what runs on each. An application's own aggregators join it with app.api.registerAggregator(name, aggregator, { nav: true }), before logs, or { nav: { after: 'logs' } } (before or after any registered section; last when that section isn't registered).

You can change that using an environment variable:

PORT=80 npm start config/custom

Tutorials

• Monitor web traffic with syslog input from Apache
• Monitor web traffic with Node/Express middleware integration

License

Apache License, version 2