Pim van Pelt
5a7e2f77f1
Full implementation of the nginx dynamic module with: - SO_BINDTODEVICE-based per-interface traffic attribution - Per-worker lock-free counters flushed to shared memory - Prometheus text and JSON scrape endpoint at configurable location - UDP-only global logtail (ipng_stats_logtail) for fire-and-forget access log streaming - $ipng_source_tag nginx variable for use in log_format/map - Histogram buckets, EWMA rate gauges, zone meta-metrics - Debian packaging (libnginx-mod-http-ipng-stats) - Robot Framework end-to-end tests via containerlab - SPDX Apache-2.0 headers on all source files
43 lines
1.7 KiB
Markdown
43 lines
1.7 KiB
Markdown
<!-- SPDX-License-Identifier: Apache-2.0 -->
|
|
# nginx-ipng-stats-plugin
|
|
|
|
Per-VIP, per-device traffic counters for nginx. Ships as a dynamic nginx module and a Debian package that loads into stock upstream
|
|
nginx on Debian Trixie.
|
|
|
|
The module attributes every HTTP request to the interface it arrived on, using Linux `SO_BINDTODEVICE` on per-interface listening
|
|
sockets. Counters — requests, status codes, bytes, latency histograms — are exposed as Prometheus text or JSON from a single HTTP
|
|
scrape endpoint, filtered per-source. This is useful for any deployment where traffic arrives on distinct interfaces — GRE tunnels,
|
|
VLANs, bonded links, or plain ethernet — and per-interface observability is needed.
|
|
|
|
Without any `device=`/`ipng_source_tag=` parameters, the module still counts and exposes per-VIP traffic under the configurable
|
|
default source tag (`direct`), which makes it a useful plain observability module for any nginx host.
|
|
|
|
See [`docs/design.md`](docs/design.md) for the full design, including the attribution model, data flow, and requirements.
|
|
|
|
## Quick start
|
|
|
|
```
|
|
make install-deps # install build and test dependencies (apt)
|
|
make build # build the .so out-of-tree
|
|
make pkg-deb # build a .deb package
|
|
make robot-test # run end-to-end tests via containerlab
|
|
```
|
|
|
|
## Installing
|
|
|
|
```
|
|
sudo dpkg -i build/*.deb
|
|
```
|
|
|
|
The package installs the `.so` into `/usr/lib/nginx/modules`, drops a `load_module` stanza into `/etc/nginx/modules-enabled/`, and runs
|
|
`nginx -t` before completing.
|
|
|
|
## Configuring
|
|
|
|
See [`docs/user-guide.md`](docs/user-guide.md) for an end-to-end walkthrough and [`docs/config-guide.md`](docs/config-guide.md) for the
|
|
directive and `listen` parameter reference.
|
|
|
|
## License
|
|
|
|
Apache-2.0. See [`LICENSE`](LICENSE).
|