MyTechDailyNews Software: Run Prometheus Metrics Inside NGINX Instead of a Separate Exporter

For MyTechDailyNews Software readers tracking operations tooling, Today marks an open-source release that matters for NGINX estates: Categorica has released nginx-stats-prometheus, an NGINX plugin that exposes Prometheus-compatible statistics from the web server process itself. The change is most relevant to teams that already use NGINX for reverse proxy or static delivery, Prometheus for collection, and Grafana for visualization.

What changed, and why it matters

The previous default path for these teams was NGINX Prometheus Exporter, a standalone exporter that usually needs its own HTTP listener. In many environments it is run under systemd or as a Docker side-car container. Neither approach is inherently broken, but both add an extra process to inventory, deploy, secure, and monitor. That is the point where the old question appears: who watches the watchmen? For a small metrics endpoint, the answer can become an extra deployment loop that does not obviously improve observability.

Categorica kept the collection idea but moved it inside NGINX. The result is one fewer separate daemon in the request path. As of today, the code is available under an MIT license, and documentation is hosted in the project's Github repository. The trade-off is deliberate: the plugin is not a full replacement for nginx-prometheus-exporter. It collects significantly fewer statistics, is tied to the NGINX version built against, and has seen far less field use.

Who should consider it

• Operators with NGINX already on hosts: If NGINX is installed from source and metrics are only needed for HTTP counters, connection states, and basic server or upstream activity, the plugin may reduce deployment surface.
• Developers reviewing build compatibility: The module is built from NGINX sources, so version alignment is important when NGINX changes.
• IT support staff validating endpoints: The route can be checked locally with curl, then wired into Prometheus scrape configuration.
• Teams using Grafana: After Prometheus scrapes the route, existing dashboards can be built from the exposed metric families.

Teams needing the broadest exporter metric coverage or wanting to avoid recompiling after NGINX updates should keep a standalone path in mind.

Prerequisites before building the plugin

Build environment checklist

The steps assume a Unix-like environment. They are easiest to follow in a terminal, but do not require advanced packaging knowledge. A basic understanding of the GNU configure, make, make install sequence is useful; it is not strictly mandatory.

• NGINX sources are needed to compile the module, even if NGINX is not rebuilt from source.
• The Makefile can obtain the NGINX sources needed for the plugin.
• If NGINX is installed from a package manager or otherwise not rebuilt, it must have been compiled with --with-compat and --with-http_stub_status_module.
• A C99 compiler is required; Clang is one example.
• The PCRE, OpenSSL, and zlib libraries and headers must be present.

Two build paths

The first path builds NGINX from source, ensuring the required features are compiled in. The second path uses an already installed NGINX and relies on the plugin Makefile to match the installed version.

Building NGINX can be skipped when a compatible installation already exists. From a terminal:

cd path-to-nginx-source
export NGINX_SRC=$(pwd)
./configure --with-compat --with-http_stub_status_module
make -j
sudo make install

This installs NGINX, typically under a /usr/local prefix. Project documentation for NGINX should be consulted for build details.

To build the plugin, the Makefile can call nginx -v, determine the installed NGINX version, and download matching NGINX sources. To skip that check, set NGINX_SRC to the local source path, then compile and install:

make module
sudo make install

That places the shared object in the standard module directory.

Configure the metrics route

After the module exists, the NGINX configuration needs a route to expose statistics. The configuration below listens on 9100 and serves a metrics endpoint. Shared memory size can be set from 1m default to another value such as 2m.

load_module modules/ngx_http_stats_prom_module.so;

http {
  # Optional: set shared memory size, default 1m
  # prometheus_metrics_shm_size 2m;
  server {
    listen 9100;
    location /metrics {
      prometheus_metrics;
    }
  }
}

On a local instance, the endpoint can then be queried:

curl http://localhost:9100/metrics

A sample response begins with global counters and gauges:

nginx_up 1
nginx_process_pid 2985885
nginx_http_requests_total 434488
nginx_http_responses_total status=1xx 0
nginx_http_responses_total status=2xx 42598
nginx_http_responses_total status=3xx 771
nginx_http_responses_total status=4xx 77
nginx_http_responses_total status=5xx 1

Metrics exposed by the plugin

The process-level metric set is available from start, measured from process start.

Metric	Type	Labels or buckets
nginx_up	gauge	none
nginx_process_pid	gauge	none
nginx_http_requests_total	counter	none
nginx_http_responses_total	counter	status, 1xx – 5xx
nginx_http_requests_by_method_total	counter	method (GET, HEAD, POST, PUT, DELETE, OPTIONS, PATCH, other)
nginx_http_request_bytes_total	counter	none
nginx_http_response_bytes_total	counter	none
nginx_http_version_total	counter	version (1.0, 1.1, 2.0, 3.0)
nginx_http_request_duration_seconds	histogram	0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10
nginx_connections_active	gauge	none
nginx_connections_reading	gauge	none
nginx_connections_writing	gauge	none
nginx_connections_waiting	gauge	none
nginx_connections_accepted_total	counter	none
nginx_connections_handled_total	counter	none

There are also basic per-directive metrics for each server or upstream block defined in nginx.conf. They appear after the first received request on that prefix.

Metric	Type	Labels
<prefix>_requests_total	counter	server or upstream
<prefix>_response_total	counter	server or upstream, status (1xx – 5xx)
<prefix>_request_bytes_total	counter	server or upstream
<prefix>_response_bytes_total	counter	server or upstream

Capacity is bounded: at most 512 server or upstream directives are supported, prefix lengths greater than 255 characters are ignored, and only 1 megabyte of memory is allocated for statistics. If that pool is exhausted, statistics collection is silently skipped. The value can be changed with prometheus_metrics_shm_size.

Plugin versus standalone exporter

Question	nginx-stats-prometheus plugin	nginx-prometheus-exporter
Process model	Runs inside NGINX	Runs as its own process
Metric breadth	Significantly fewer statistics	Fully featured exporter
Update burden	Tied to the NGINX version built against; updates typically require rebuilding	Independent process update model
Maturity	Far less battle tested	More common and more mature

Common misconceptions

• It is a drop-in replacement. No. It is an in-process route, but the metric set is narrower than the standalone exporter.
• It can survive NGINX upgrades silently. Not safely. Because the plugin is tied to the built NGINX version, plan to rebuild after an NGINX update.
• All metrics are visible before traffic arrives. Process-wide metrics are available at launch, while per-server and per-upstream counters appear only after the first received request on that prefix.
• More server blocks always work. The module supports at most 512 directives and ignores prefixes longer than 255 characters.

FAQ

Can the Makefile download the needed NGINX sources automatically? Yes, if an appropriate NGINX version is installed; it can query nginx -v, determine the version, and fetch the matching sources. Set NGINX_SRC to skip that workflow.

Do I need to rebuild NGINX? Not always. If an existing NGINX build includes the required compatibility and stub-status features, the plugin build can work with the NGINX sources. If not, building from source gives the clearest path to the needed features.

Where is the license information? The release is under MIT, and the README is in the project's Github repository.

Is support available? No. The current release states that no support is offered and that help with issues cannot be guaranteed.

Action checklist before switching

1. Record the installed NGINX version and compile flags, especially --with-compat and --with-http_stub_status_module.
2. Confirm that the required metrics are present in the plugin table; if full exporter coverage is needed, retain the standalone path.
3. Compile the plugin in a Unix-like environment with a C99 compiler and PCRE, OpenSSL, and zlib headers.
4. Expose the route on 9100 or another approved port, then validate with curl.
5. Review prometheus_metrics_shm_size against expected server and upstream counts; remember the default is 1m and only 1 megabyte is allocated unless changed.
6. Add a rebuild task to the NGINX change window, because updates typically require rebuilding the plugin.
7. Document that the release is MIT-licensed, has no support, and is far less battle tested than nginx-prometheus-exporter.

For readers who want to keep NGINX without containerization, simplify deployment configuration, or run metrics collection from a plugin, nginx-stats-prometheus is worth evaluating.