diff --git a/.gitignore b/.gitignore index 7cf02e1..1d3b4bd 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ build/ objs/ *.so *.o +src/version.h # Debian build outputs (dpkg-buildpackage writes these to the parent dir, # but if a helper extracts them here, ignore them) diff --git a/Makefile b/Makefile index 04d6a3a..975ef71 100644 --- a/Makefile +++ b/Makefile @@ -18,9 +18,16 @@ MODULE_NAME := ngx_http_ipng_stats_module MODULE_DIR := $(CURDIR) BUILD_DIR := $(CURDIR)/build +# Single source of truth for the module version. When cutting a release, +# bump this AND add a matching top entry to debian/changelog — dpkg reads +# the package version from there directly. The C code picks up VERSION +# via the generated src/version.h (written by the version-header target +# below and depended on by the module build). +VERSION := 0.2.0 + NGINX_SRC ?= -.PHONY: help build pkg-deb robot-test install-deps clean fetch-nginx-src +.PHONY: help build pkg-deb robot-test install-deps clean fetch-nginx-src version-header TEST ?= tests/ @@ -50,7 +57,19 @@ build: $(BUILD_DIR)/$(MODULE_NAME).so @echo " echo 'load_module modules/$(MODULE_NAME).so;' | sudo tee /etc/nginx/modules-enabled/50-mod-http-ipng-stats.conf" @echo " sudo nginx -t && sudo nginx -s reload" -$(BUILD_DIR)/$(MODULE_NAME).so: fetch-nginx-src +# version-header: write src/version.h iff its contents would change. The +# target is .PHONY so it's re-evaluated every build, but the file itself +# is only touched on VERSION bumps — keeps the .so from rebuilding when +# nothing has actually changed. +version-header: + @NEW='#define NGX_HTTP_IPNG_STATS_VERSION "$(VERSION)"'; \ + if [ ! -f $(MODULE_DIR)/src/version.h ] \ + || [ "$$NEW" != "$$(cat $(MODULE_DIR)/src/version.h)" ]; then \ + echo "Generating src/version.h (VERSION=$(VERSION))"; \ + echo "$$NEW" > $(MODULE_DIR)/src/version.h; \ + fi + +$(BUILD_DIR)/$(MODULE_NAME).so: version-header fetch-nginx-src @set -e; \ if [ -z "$(NGINX_SRC)" ]; then \ NGX_SRC="$(BUILD_DIR)/nginx-src"; \ @@ -154,4 +173,5 @@ install-deps: clean: rm -rf $(BUILD_DIR) tests/.venv tests/out + rm -f $(MODULE_DIR)/src/version.h -dh_clean 2>/dev/null || true diff --git a/debian/changelog b/debian/changelog index aa8d99d..dad5b35 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,23 @@ +nginx-ipng-stats-plugin (0.2.0-1) unstable; urgency=medium + + * Reduce scrape cardinality. + - Status codes are collapsed to six class lanes + (1xx/2xx/3xx/4xx/5xx/unknown) on the counter key. Per-(source, vip) + counter cardinality is now bounded at six regardless of response mix. + - Histograms drop the code label entirely and aggregate across classes + per (source, vip). + - New nginx_ipng_latency_total counter (with code class label) exposes + per-class mean latency via latency_total / requests_total. + - New nginx_ipng_bytes_in and nginx_ipng_bytes_out histograms; bucket + bounds configurable via the new ipng_stats_byte_buckets directive. + - JSON schema bumped to 2. Records are now per-(source, vip) with an + inner `classes` map. + - Operators needing per-three-digit-code breakdowns should consume + ipng_stats_logtail off-host; the stats zone intentionally trades + that resolution for a smaller, bounded scrape. + + -- Pim van Pelt Fri, 17 Apr 2026 12:36:57 +0000 + nginx-ipng-stats-plugin (0.1.0-1) unstable; urgency=medium * Initial release. diff --git a/docs/design.md b/docs/design.md index bd0a275..24598ed 100644 --- a/docs/design.md +++ b/docs/design.md @@ -5,7 +5,7 @@ | | | | --- | --- | -| **Status** | Draft — describes intended behavior for `v0.1.0` | +| **Status** | Draft — describes intended behavior for `v0.2.0` | | **Author** | Pim van Pelt `` | | **Last updated** | 2026-04-16 | | **Audience** | Operators and contributors deploying per-device, per-VIP traffic observability on nginx | diff --git a/docs/user-guide.md b/docs/user-guide.md index 460f43a..2638e5f 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -23,7 +23,7 @@ On Debian Trixie (and newer), the module is distributed as `libnginx-mod-http-ip package and loads cleanly into it without recompiling nginx itself. ``` -sudo apt install ./libnginx-mod-http-ipng-stats_0.1.0-1_amd64.deb +sudo apt install ./libnginx-mod-http-ipng-stats_*_amd64.deb ``` The package will: diff --git a/src/ngx_http_ipng_stats_module.c b/src/ngx_http_ipng_stats_module.c index 7db82c4..376f254 100644 --- a/src/ngx_http_ipng_stats_module.c +++ b/src/ngx_http_ipng_stats_module.c @@ -66,7 +66,9 @@ typedef struct { extern ngx_module_t ngx_http_log_module; -#define NGX_HTTP_IPNG_STATS_VERSION "0.1.0" +/* NGX_HTTP_IPNG_STATS_VERSION is generated at build time from the + * top-level Makefile's VERSION variable — see `make version-header`. */ +#include "version.h" #define NGX_HTTP_IPNG_STATS_SCHEMA_VERSION 2 /* Default histogram buckets in milliseconds (FR-2.3). */ diff --git a/tests/01-module/01-e2e.robot b/tests/01-module/01-e2e.robot index 12bc3ec..0e15d19 100644 --- a/tests/01-module/01-e2e.robot +++ b/tests/01-module/01-e2e.robot @@ -40,7 +40,7 @@ JSON scrape ${rc} ${output} = Run And Return Rc And Output ... curl -sf -H 'Accept: application/json' ${SCRAPE_URL} | python3 -m json.tool Should Be Equal As Integers ${rc} 0 - Should Contain ${output} "schema": 1 + Should Contain ${output} "schema": 2 # --- Per-device attribution ---