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.