46 lines
2.1 KiB
Markdown
46 lines
2.1 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, reading the ingress `ifindex` per connection from the
|
|
kernel's `IP_PKTINFO` / `IPV6_PKTINFO` cmsg. Listening sockets stay plain wildcards, so outgoing packets follow the normal
|
|
routing table — which is what makes this safe for DSR / maglev deployments where the SYN arrives via a GRE tunnel and the
|
|
SYN-ACK must leave via the default route. Counters — requests, status codes, bytes, latency histograms — plus point-in-time
|
|
gauges of requests currently in flight (`active`, `reading`, `writing`) 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).
|