Files

Pim van Pelt 5a7e2f77f1 Add ngx_http_ipng_stats_module: per-VIP, per-device traffic counters

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

2026-04-16 17:41:23 +02:00

1.7 KiB

Raw Blame History

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 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 for an end-to-end walkthrough and docs/config-guide.md for the directive and listen parameter reference.

License

Apache-2.0. See LICENSE.