@hyperwatch/hyperwatch 4.3.1 → 5.0.0

package/README.md

@@ -12,9 +12,9 @@ Hyperwatch is built on a real-time stream processor handling logs from inputs of
 
 ## Install
 
-Make sure you have Node.js version >= 20.
+Make sure you have Node.js version >= 24.
 
-We recommend using [nvm](https://github.com/creationix/nvm): `nvm install && nvm use`.
+We recommend using [nvm](https://github.com/nvm-sh/nvm): `nvm install && nvm use`.
 
 ```bash
 git clone https://github.com/hyperwatch/hyperwatch.git
@@ -42,7 +42,7 @@ In order to do this, you need to create a new configuration file such as `config
 
 See [Input Configuration](./docs/input.md) for the list of available input types and how to configure them.
 
-There are also a couple of constants you might configure with a simple config file, to learn more you can head to [Constants Configuration](./docs/configuration.md).
+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](./docs/configuration.md).
 
 ### Start with custom configuration
 
@@ -50,7 +50,7 @@ There are also a couple of constants you might configure with a simple config fi
 npm start config/custom
 ```
 
-The Hyperwatch API and Websocket will be served from port `3000` by default.
+The Hyperwatch API and WebSocket will be served from port `3000` by default. Open `http://localhost:3000/status` to check the status of your inputs.
 
 You can change that using an environment variable:
 
@@ -58,6 +58,11 @@ You can change that using an environment variable:
 PORT=80 npm start config/custom
 ```
 
+## Tutorials
+
+- [Monitor web traffic with syslog input from Apache](./docs/tutorials/apache_input.md)
+- [Monitor web traffic with Node/Express middleware integration](./docs/tutorials/express_input.md)
+
 ## License
 
 [Apache License, version 2](LICENSE)

package/config/apache_syslog_example.js

@@ -14,7 +14,7 @@ module.exports = function (hyperwatch) {
   const syslogApacheHyperwatchCombinedInput = input.syslog.create({
     port: 1518,
     parse: format.apache.parser({
-      format: format.apache.formats.hyperwatchCombined,
+      format: format.apache.formats.hyperwatch_combined,
     }),
   });
 

package/config/default.js

@@ -27,7 +27,7 @@ const defaultConfig = function (hyperwatch) {
     name: 'Syslog (nginx hyperwatch_combined format)',
     port: 1515,
     parse: format.nginx.parser({
-      format: format.nginx.formats.hyperwatchCombined,
+      format: format.nginx.formats.hyperwatch_combined,
     }),
   });
 

package/config/example.js

@@ -27,7 +27,7 @@ const exampleConfig = function (hyperwatch) {
     name: 'Syslog (nginx hyperwatch_combined format)',
     port: 1515,
     parse: format.nginx.parser({
-      format: format.nginx.formats.hyperwatchCombined,
+      format: format.nginx.formats.hyperwatch_combined,
     }),
   });
 
@@ -60,7 +60,7 @@ const exampleConfig = function (hyperwatch) {
     name: 'Syslog (apache hyperwatch_combined format)',
     port: 1518,
     parse: format.apache.parser({
-      format: format.apache.formats.hyperwatchCombined,
+      format: format.apache.formats.hyperwatch_combined,
     }),
   });
 
@@ -121,7 +121,7 @@ const exampleConfig = function (hyperwatch) {
   //   name: 'File input (nginx hyperwatch_combined format)',
   //   path: '/var/log/nginx/hyperwatch.log',
   //   parse: format.nginx.parser({
-  //     format: format.nginx.formats.hyperwatchCombined,
+  //     format: format.nginx.formats.hyperwatch_combined,
   //   }),
   // });
 
@@ -145,7 +145,7 @@ const exampleConfig = function (hyperwatch) {
   //   name: 'File input (nginx hyperwatch_combined format)',
   //   path: '/var/log/apache2/hyperwatch.log',
   //   parse: format.nginx.parser({
-  //     format: format.apache.formats.hyperwatchCombined,
+  //     format: format.apache.formats.hyperwatch_combined,
   //   }),
   // });
 

package/config/express_websocket_example.js

@@ -8,7 +8,7 @@ module.exports = function (hyperwatch) {
   /* Input configuration */
   /* =================== */
 
-  /* Syslog input  */
+  /* WebSocket input */
   /* ------------- */
 
   const webSocketServerInput = input.websocket.create({

package/config/websocket_client_example.js

@@ -0,0 +1,52 @@
+/*
+ * Subscribe to the raw logs of an app embedding Hyperwatch (see
+ * docs/express-embedding.md) with a WebSocket client input, enrich them, and
+ * print them.
+ *
+ *   HYPERWATCH_SECRET=… npm start config/websocket_client_example
+ *
+ * Environment:
+ * - HYPERWATCH_URL: the app's raw log stream
+ *   (default: ws://localhost:3000/_hyperwatch/logs/raw, an app running locally)
+ * - HYPERWATCH_USERNAME / HYPERWATCH_SECRET: the app's Basic Auth credentials
+ *   (the username defaults to hyperwatch)
+ * - PORT: where this watcher serves its API (default: 4000)
+ */
+
+module.exports = function (hyperwatch) {
+  const { pipeline, input, logger } = hyperwatch;
+
+  const {
+    HYPERWATCH_URL = 'ws://localhost:3000/_hyperwatch/logs/raw',
+    HYPERWATCH_USERNAME = 'hyperwatch',
+    HYPERWATCH_SECRET,
+  } = process.env;
+
+  hyperwatch.init({
+    // Not 3000, so the watcher doesn't clash with an app running locally
+    port: 4000,
+    modules: {
+      cloudflare: { active: true },
+      geoip: { active: true },
+      agent: { active: true },
+      hostname: { active: true },
+      identity: { active: true },
+    },
+  });
+
+  // Fetch the logs
+  pipeline.registerInput(
+    input.websocket.create({
+      type: 'client',
+      address: HYPERWATCH_URL,
+      username: HYPERWATCH_USERNAME,
+      password: HYPERWATCH_SECRET,
+      reconnectOnClose: true,
+    })
+  );
+
+  // Output them, enriched
+  pipeline
+    .getNode('main')
+    .map((log) => console.log(logger.defaultFormatter.format(log, 'console')));
+};

package/docs/configuration.md

@@ -6,20 +6,81 @@ Our recommended way to configure the constants is to add a `.hyperwatchrc` at th
 
 This file can be in either `JSON` (recommended) or `ini` format.
 
-Here is an example of how this file can look like :
+Here is an example of how this file can look like:
 
 ```JSON
 {
-  "port": 4000
+  "port": 4000,
+  "modules": {
+    "logs": { "active": true },
+    "agent": { "active": true },
+    "address": { "active": true }
+  },
+  "persistence": { "enabled": true }
 }
 ```
 
-This example would make the app be served on the 4000 port.
+This example would serve the app on port 4000, enable the live log streams, User-Agent parsing and the addresses aggregator, and keep aggregated data between restarts.
+
+Values are merged with the defaults, so you only need to list what you change.
+
+Constants can also be passed from a configuration file, as an argument of `hyperwatch.init()`:
+
+```javascript
+module.exports = function (hyperwatch) {
+  hyperwatch.init({ modules: { logs: { active: true } } });
+  // ...
+};
+```
 
 You can find below the list of all configurable constants:
 
 ## Global
 
-| Constant name | Type    | Description                    |
-| ------------- | ------- | ------------------------------ |
-| port          | integer | The port the app is running on |
+| Constant name     | Type    | Default | Description                                            |
+| ----------------- | ------- | ------- | ------------------------------------------------------ |
+| port              | integer | `3000`  | The port the app is running on                         |
+| heartbeatInterval | integer | `30000` | Interval in ms between WebSocket pings sent to clients |
+
+The `PORT` environment variable takes precedence over the `port` constant.
+
+## Modules
+
+Modules enrich logs and expose API endpoints. Each module is configured under `modules.<name>` with:
+
+| Attribute | Type    | Description                                                  |
+| --------- | ------- | ------------------------------------------------------------ |
+| active    | boolean | Whether the module is loaded                                 |
+| priority  | integer | Modules are loaded in ascending priority. Keep the defaults. |
+
+Only `status` is active by default.
+
+| Module     | Description                                                                                                                       | Endpoints              |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| status     | Status of inputs and pipeline nodes                                                                                               | `/status`              |
+| logs       | Streams every pipeline node over HTTP and WebSocket                                                                               | `/logs/<node>`         |
+| cloudflare | Uses Cloudflare headers (`cf-connecting-ip`, `cf-ipcountry`, `cf-ray`) for the client address and data                            | –                      |
+| geoip      | Geolocates addresses                                                                                                              | –                      |
+| agent      | Parses User-Agents with [@hyperwatch/useragent](https://github.com/hyperwatch/useragent)                                          | –                      |
+| hostname   | Reverse DNS lookup and forward verification of client addresses                                                                   | –                      |
+| language   | Parses the `Accept-Language` header                                                                                               | –                      |
+| dnsbl      | Checks client addresses against DNS blocklists                                                                                    | –                      |
+| address    | Aggregates traffic per address                                                                                                    | `/addresses`           |
+| signature  | Aggregates traffic per request signature                                                                                          | `/signatures`          |
+| identity   | Identifies known robots and crawlers. Depends on `agent`, `hostname`, `signature` and `address`                                   | `/identities`          |
+| history    | Keeps the latest logs of each pipeline node in memory (`capacity`, default `1000`), saved and restored when `persistence.enabled` | `/history/<node>.json` |
+| sparkline  | Adds activity sparklines to aggregator HTML tables                                                                                | –                      |
+
+Aggregator endpoints render an HTML table by default, or JSON and CSV with a `.json` or `.csv` extension. They accept `limit` (default `100`) and `sort` (default `count15m`) query parameters. A single entry is available at `/<aggregator>/<id>.json`, and `DELETE /<aggregator>` resets it.
+
+To use a custom DNS server for the `hostname` module, set the `HYPERWATCH_DNS_SERVER` environment variable.
+
+## Persistence
+
+Aggregated data can be saved when Hyperwatch stops and loaded when it starts.
+
+| Constant name         | Type    | Default            | Description                                      |
+| --------------------- | ------- | ------------------ | ------------------------------------------------ |
+| persistence.enabled   | boolean | `false`            | Whether to save and load aggregator data         |
+| persistence.path      | string  | `.hyperwatch-data` | Directory for the data, relative to the cwd      |
+| persistence.namespace | string  | `null`             | Optional sub-directory, to run several instances |

package/docs/express-embedding.md

@@ -0,0 +1,137 @@
+# Express embedding
+
+Hyperwatch can run inside an existing Express 5 application, instead of running as a separate server. The app logs its own traffic and exposes the Hyperwatch API and live streams (HTTP and WebSocket) on its own port, under a path you choose.
+
+```javascript
+const http = require('node:http');
+const express = require('express');
+const basicAuth = require('express-basic-auth');
+const hyperwatch = require('@hyperwatch/hyperwatch');
+
+const {
+  PORT = 3000,
+  HYPERWATCH_USERNAME = 'hyperwatch',
+  HYPERWATCH_SECRET,
+} = process.env;
+
+const app = express();
+const server = http.createServer(app);
+
+hyperwatch.init({ modules: { logs: { active: true } } });
+
+// Log every request: register the input before other middleware and routes
+const input = hyperwatch.input.express.create();
+app.use(input.middleware());
+hyperwatch.pipeline.registerInput(input);
+
+// Mount the Hyperwatch API and live streams, behind authentication
+const auth = basicAuth({ users: { [HYPERWATCH_USERNAME]: HYPERWATCH_SECRET } });
+
+hyperwatch.app.mount(app, {
+  server,
+  path: '/_hyperwatch',
+  middleware: auth,
+});
+
+// Other middleware and application routes
+
+hyperwatch.modules.start();
+hyperwatch.pipeline.start();
+server.listen(PORT);
+```
+
+Don't call `hyperwatch.start()`: it would start the standalone Hyperwatch server.
+
+## `hyperwatch.app.mount(app, options)`
+
+| Option       | Required | Description                                                                                                      |
+| ------------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
+| `server`     | yes      | The Node HTTP server of the app. `mount()` adds an `upgrade` listener to it, and never creates or starts one.    |
+| `path`       | yes      | The mount path, e.g. `'/_hyperwatch'`. It must start with `/` and not end with `/`.                              |
+| `middleware` | no       | A middleware function or an array of them, e.g. authentication. Applied to HTTP requests and WebSocket upgrades. |
+| `fallback`   | no       | `(req, socket, head) => {}`, called with the WebSocket upgrades Hyperwatch doesn't own.                          |
+
+### HTTP routes
+
+`mount()` calls `app.use(path, ...middleware, router)`, at the point where it's called. The app's middleware order is kept:
+
+- Middleware registered before `mount()` runs for Hyperwatch requests too. Mount Hyperwatch before a rate limiter if the watcher shouldn't be limited.
+- Routes registered before `mount()` can answer first: mount Hyperwatch before a catch-all route (e.g. a Next.js request handler).
+
+### WebSocket upgrades
+
+`mount()` adds one `upgrade` listener to `server`:
+
+- An upgrade with a malformed target (not an origin-form `/path?query`, e.g. `//[/` or an absolute URL) gets `400 Bad Request`, before reaching the app or `fallback`.
+- An upgrade under the mount path (`/_hyperwatch` or `/_hyperwatch/…`) is sent through `app`, like an HTTP request. It goes through the same middleware, so authentication protects it, and Express answers errors as usual: a middleware can reject it with `401`, `next(error)` keeps the error's status, and an unknown Hyperwatch route gets `404`.
+- Any other upgrade is passed to `fallback(req, socket, head)` when given. Otherwise it's left to the server's other `upgrade` listeners.
+
+Hyperwatch only owns its mount path: `/other/logs/raw` is never handled by Hyperwatch, even though `/logs/raw` is a Hyperwatch route. The mount path is matched like Express matches `app.use()`: case-insensitively by default, and case-sensitively when the app enables `case sensitive routing`. So an HTTP request and a WebSocket upgrade to the same path always reach the same place.
+
+`mount()` doesn't stop the server's other `upgrade` listeners from receiving Hyperwatch upgrades. A listener that closes the sockets of upgrades it doesn't serve would close the Hyperwatch WebSocket. Give such a component its own channel, and pass it the other upgrades with `fallback`, as below for Next.js.
+
+### Mounting twice, and cleanup
+
+`mount()` throws, before registering anything, when:
+
+- Hyperwatch is already mounted on the same `server`.
+- Hyperwatch was already mounted on the same app at the same path, matched like the app routes it (so `/_HYPERWATCH` is the same path by default). This holds even after `detachUpgrades()`: Express can't remove routes, so the first mount keeps answering at that path, with its original middleware. Mounting again couldn't change them, e.g. add authentication.
+
+`mount()` returns `{ path, detachUpgrades }`. `detachUpgrades()` removes the `upgrade` listener, so Hyperwatch stops handling WebSocket upgrades, and releases the server for a mount at another path. It can be called several times. It doesn't unmount the HTTP routes, which stay mounted with their middleware.
+
+## Next.js custom server (workaround for Next.js 16.3)
+
+Next.js registers an `upgrade` listener for its own WebSockets (e.g. hot reload in development) on the server it runs behind: the `httpServer` option, or the server of the first request it handles. It ends the socket of any upgrade whose path matches one of its routes, e.g. a catch-all page, which includes `/_hyperwatch/logs/raw`.
+
+So Next.js gets its own upgrade channel, and Hyperwatch passes it the upgrades it doesn't own:
+
+```javascript
+const { EventEmitter } = require('node:events');
+const next = require('next');
+
+// Next.js listens for upgrades on this channel, not on the server
+const nextUpgrades = new EventEmitter();
+const nextApp = next({ dev, httpServer: nextUpgrades });
+const handle = nextApp.getRequestHandler();
+
+hyperwatch.app.mount(app, {
+  server,
+  path: '/_hyperwatch',
+  middleware: auth,
+  fallback: (req, socket, head) =>
+    nextUpgrades.emit('upgrade', req, socket, head),
+});
+
+// Next.js renders the pages, after Hyperwatch
+app.use((req, res) => handle(req, res));
+```
+
+This is a version-specific workaround, not a stable integration contract. Next.js documents `httpServer` as the HTTP server it runs behind, and doesn't offer a way to keep its upgrade listener off a custom server. In Next.js 16.3, `httpServer` is only used to listen for `upgrade` events, so an `EventEmitter` works: verified with Next.js 16.3.4 in development (hot reload) and production, with a catch-all page. Check it again when upgrading Next.js.
+
+## Subscribing to the live logs
+
+A watcher can subscribe to the logs with a WebSocket input:
+
+```javascript
+const { HYPERWATCH_USERNAME = 'hyperwatch', HYPERWATCH_SECRET } = process.env;
+
+input.websocket.create({
+  type: 'client',
+  address: 'wss://example.org/_hyperwatch/logs/raw',
+  username: HYPERWATCH_USERNAME,
+  password: HYPERWATCH_SECRET,
+  reconnectOnClose: true,
+});
+```
+
+`config/websocket_client_example.js` is a complete watcher: it subscribes to the logs of an app running locally, enriches them and prints them.
+
+```sh
+HYPERWATCH_SECRET=… npm start config/websocket_client_example
+```
+
+## Upgrading from express-ws
+
+With Hyperwatch 4.3 and Express 4, an app would call `expressWs(app)` and mount `hyperwatch.app.api` and `hyperwatch.app.websocket` itself. Express 5 is not compatible with express-ws, and Hyperwatch no longer uses it.
+
+`hyperwatch.app.websocket` is still an Express middleware, so `app.use(path, hyperwatch.app.websocket)` doesn't throw, but on its own it doesn't handle any upgrade. Replace the express-ws setup and the `app.use()` calls with `hyperwatch.app.mount()`.

package/docs/input.md

@@ -3,15 +3,16 @@
 Input configuration consists in 3 steps:
 
 1. Instantiating a [type of input](#input-types) with the right configuration
-2. Optionnaly indicating to the input [how to parse the access logs](#other-formats)
+2. Optionally indicating to the input [how to parse the access logs](#other-formats)
 3. Registering the input with the pipeline
 
-You can configure and register as many inputs as you need. The web interface will show you the configured inputs, their status and how much traffic is going through them.
+You can configure and register as many inputs as you need. The `/status` page shows the configured inputs, their status and how much traffic is going through them.
 
 ## Input Types
 
 - All inputs support by default single logs in the [Hyperwatch JSON format](#json-format).
 - All inputs support an optional `parse` parameter for other formats.
+- All inputs accept an optional `name`, displayed on the `/status` page.
 
 ### Syslog
 
@@ -66,7 +67,7 @@ The input accepts the following options.
 
 ### WebSocket
 
-The WebSocket input subscribe to a WebSocket server sending access logs.
+The WebSocket input subscribes to a WebSocket server sending access logs (`client`), or listens for WebSocket connections sending access logs (`server`).
 
 The input accepts the following options.
 
@@ -75,9 +76,29 @@ The input accepts the following options.
 | type      | string | no                        | Either 'client' or 'server' (default to 'client')                                        |
 | address   | string | yes (if type is 'client') | The WebSocket address to connect to (e.g. 'wss://localhost:3000')                        |
 | path      | string | yes (if type is 'server') | The path where to listen for logs                                                        |
-| parse     | Parser | no                        | A function to parse the messages from the queue (See Formats below)                      |
+| parse     | Parser | no                        | A function to parse the messages (See [Formats](#other-formats) below)                   |
 | sample    | float  | no                        | A sample rate, a float between 0 and 1. Will only send data this percentage of the time. |
 
+### Express
+
+The Express input receives logs from a middleware mounted in an Express application running in the same process as Hyperwatch.
+
+Mount its middleware before the application routes, so every request is logged:
+
+```javascript
+const expressInput = input.express.create();
+app.use(expressInput.middleware()); // Before application routes
+pipeline.registerInput(expressInput);
+```
+
+| Attribute | Type    | Required? | Description                                                                             |
+| --------- | ------- | --------- | --------------------------------------------------------------------------------------- |
+| app       | Express | no        | An Express app to mount the middleware on when the pipeline starts. See the note below. |
+
+**Note**: With the `app` option, the input calls `app.use()` only when the pipeline starts. Routes registered on the app before that run first, and their requests are not logged, even if they are declared after `input.express.create()`. Prefer mounting `middleware()` yourself, as above.
+
+To log the traffic of an application running in a separate process, use the [Hyperwatch Express Logger](https://www.npmjs.com/package/@hyperwatch/express-logger) middleware with the HTTP, WebSocket or syslog input (see the [tutorial](./tutorials/express_input.md)).
+
 ## JSON Format
 
 The JSON log parser parses access log in JSON that match the following schema.
@@ -143,7 +164,7 @@ If you are using Nginx, you can simply copy-and-paste the format specification f
   parse: format.nginx.parser({
     format:
       '$remote_addr - $remote_user [$time_local] "$request" $status $bytes_sent "$http_referer" "$http_user_agent"',
-  });
+  }),
 }
 ```
 
@@ -167,7 +188,7 @@ If you are using Apache, you can simply copy-and-paste the format specification
 {
   parse: format.apache.parser({
     format: '%h %l %u %t "%r" %>s %b "%{Referer}i" "%{User-agent}i"',
-  });
+  }),
 }
 ```
 
@@ -202,21 +223,23 @@ If you're using a standard log format, do not hesitate to create a ticket in the
 Simple real-time log processing of [Nginx's predefined combined](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) log format with a log file located at `/var/log/nginx/access.log` can be achieved with the following configuration:
 
 ```javascript
-const pipeline = require('../lib/pipeline');
-const input = require('../input');
-const format = require('../format');
+module.exports = function (hyperwatch) {
+  const { pipeline, input, format } = hyperwatch;
 
-const nginxInput = input.file.create({
-  path: '/var/log/nginx/access.log',
-  parse: format.nginx.parser({ format: format.nginx.formats.combined }),
-});
+  hyperwatch.init();
 
-pipeline.registerInput(nginxInput);
+  const nginxInput = input.file.create({
+    path: '/var/log/nginx/access.log',
+    parse: format.nginx.parser({ format: format.nginx.formats.combined }),
+  });
+
+  pipeline.registerInput(nginxInput);
+};
 ```
 
 When placed in `config/custom.js` it can be used by Hyperwatch with:
 
-```
+```bash
 npm start config/custom
 ```
 
@@ -224,36 +247,39 @@ npm start config/custom
 
 For more detailed log processing, it is recommended to use the _Hyperwatch combined_ log format:
 
-```
+```nginx
 log_format hyperwatch_combined '$remote_addr - $remote_user [$time_local] "$request" $status $bytes_sent "$http_referer" "$http_user_agent" "$http_accept" "$http_accept_charset" "$http_accept_encoding" "$http_accept_language" "$http_connection" "$http_dnt" "$http_from" "$http_host"'
 access_log /logs/access.log hyperwatch_combined;
 ```
 
 With the following configuration for Hyperwatch:
 
-```
+```javascript
 const defaultInput = input.file.create({
   path: '/logs/access.log',
-  parse: format.nginx.parser({format: format.nginx.formats.hyperwatch_combined})
-})
+  parse: format.nginx.parser({
+    format: format.nginx.formats.hyperwatch_combined,
+  }),
+});
 ```
 
 ### Behind a proxy
 
 If behind a proxy, you might want to also report the `HTTP_X_FORWARDED_FOR` header to allow Hyperwatch to properly detect the client IP address.
 
-```
+```nginx
 log_format hyperwatch_combined_with_x_forwarded_for '$remote_addr - $remote_user [$time_local] "$request" $status $bytes_sent "$http_referer" "$http_user_agent" "$http_accept" "$http_accept_charset" "$http_accept_encoding" "$http_accept_language" "$http_connection" "$http_dnt" "$http_from" "$http_host" "$http_x_forwarded_for"'
 access_log /logs/access.log hyperwatch_combined_with_x_forwarded_for;
 ```
 
 With the following configuration for Hyperwatch:
 
-```
+```javascript
 const defaultInput = input.file.create({
   path: '/logs/access.log',
   parse: format.nginx.parser({
-    format: '$remote_addr - $remote_user [$time_local] "$request" $status $bytes_sent "$http_referer" "$http_user_agent" "$http_accept" "$http_accept_charset" "$http_accept_encoding" "$http_accept_language" "$http_connection" "$http_dnt" "$http_from" "$http_host" "$http_x_forwarded_for"'
-  })
-})
+    format:
+      '$remote_addr - $remote_user [$time_local] "$request" $status $bytes_sent "$http_referer" "$http_user_agent" "$http_accept" "$http_accept_charset" "$http_accept_encoding" "$http_accept_language" "$http_connection" "$http_dnt" "$http_from" "$http_host" "$http_x_forwarded_for"',
+  }),
+});
 ```

package/docs/tutorials/apache_input.md

@@ -10,10 +10,10 @@ Let's start.
 
 On the same server where Apache is running, or on a server that is reachable by it, install the Hyperwatch processor.
 
-As a prerequirement, you'll need Node.js >= 7. Use nvm if you're in trouble.
+As a prerequisite, you'll need Node.js >= 24. We recommend [nvm](https://github.com/nvm-sh/nvm).
 
 ```bash
-nvm install node
+nvm install 24
 ```
 
 #### Install from npm
@@ -24,7 +24,7 @@ npm install -g @hyperwatch/hyperwatch
 
 #### Install from Git
 
-Alternatively, for developemnt purpose, you can use Git and clone the public repository:
+Alternatively, for development purpose, you can use Git and clone the public repository:
 
 ```bash
 git clone https://github.com/hyperwatch/hyperwatch.git
@@ -34,13 +34,13 @@ npm install
 
 ### Configure Hyperwatch
 
-In our suggested configuration, Hyperwatch will be listening for access logs in the the `access_watch_combined` format on port `1518`.
+In our suggested configuration, Hyperwatch will be listening for access logs in the `hyperwatch_combined` format on port `1518`.
 
-We always recommand using the `access_watch_combined` format, which is logging more detailed information and allows for a much better analysis than the regular `combined` format.
+We always recommend using the `hyperwatch_combined` format, which is logging more detailed information and allows for a much better analysis than the regular `combined` format.
 
-To get more familiar, you can inspect default and example configurations in [`config/default.js`](<(../../config/default.js)>) and [`config/example.js`](../../config/example.js) file.
+To get more familiar, you can inspect default and example configurations in [`config/default.js`](../../config/default.js) and [`config/example.js`](../../config/example.js) file.
 
-Now, you can create your own configuration in `apache_syslog_example.js`:
+Now, you can create your own configuration in `apache_syslog_example.js` (a complete version is available in [`config/apache_syslog_example.js`](../../config/apache_syslog_example.js)):
 
 ```javascript
 module.exports = function (hyperwatch) {
@@ -61,7 +61,7 @@ module.exports = function (hyperwatch) {
 
 ### Configure Apache
 
-First, if you're following our recommendation and opted for the `hyperwatch_combined` format, you need to define it in the Apache configuration. This will not replace the standard log format, just create an additional one.
+First, if you're following our recommendation and opted for the `hyperwatch_combined` format, you need to define it in the Apache configuration. This will not replace the standard log format, just create an additional one.
 
 ```
 LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\" \"%{Accept}i\" \"%{Accept-Charset}i\" \"%{Accept-Encoding}i\" \"%{Accept-Language}i\" \"%{Connection}i\" \"%{Dnt}i\" \"%{From}i\" \"%{Host}i\"" hyperwatch_combined
@@ -79,13 +79,13 @@ Note: This is known to be working on _Ubuntu 16.04, 18.04_ with _logger 2.27.1,
 
 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. We configured Hyperwatch to listen for syslog messages in the `hyperwatch_combined` format on port `1518`.
+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. We configured Hyperwatch to listen for syslog messages in the `hyperwatch_combined` format on port `1518`.
    We're properly passing that port in the configuration
-3. Finally, we're asking Apache to use the `hyperwatch_combined` log format we previously configured.
+3. Finally, we're asking Apache to use the `hyperwatch_combined` log format we previously configured.
 
-Don't forget to reload Aapche with the updated configuration. On Ubuntu, it would be:
+Don't forget to reload Apache with the updated configuration. On Ubuntu, it would be:
 
 ```bash
 service apache2 reload
@@ -101,4 +101,6 @@ hyperwatch apache_syslog_example.js
 
 ### Browse the interface
 
-Now, you can point your browser to the IP/port where Hyperwatch is running. If you see data flowing, congrats you made it!
+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](../configuration.md#modules).