nginx-module-vts is an open-source Nginx module that tracks and exposes per-virtual-host traffic statistics — request counts, response codes, and traffic totals — as JSON or HTML, built for Nginx operators who need visibility into vhost traffic without running a separate metrics agent.

What it is

nginx-module-vts is a C module written for Nginx. It lives in the Nginx module ecosystem as a server-level instrumentation layer: once compiled in and enabled with the vhost_traffic_status directive, it counts traffic in-process and publishes the result through a shared memory zone defined by vhost_traffic_status_zone. The statistics are keyed by virtual host and can be grouped, filtered, and split by arbitrary keys, which is what separates it from plain request logging. The project is maintained under the vozlt-nginx-modules topic alongside its siblings, is licensed BSD-2-Clause, and carries 3,503 stars and 489 forks.

The concrete problem it solves is per-vhost traffic accounting without out-of-band log processing. Rather than parsing access logs after the fact to reconstruct how much traffic each host, upstream, or filter key received, the module maintains counters inside Nginx itself and serves them on demand. It replaces the ad hoc combination of log rotation, log parsing, and external aggregation that would otherwise be needed to answer questions such as which virtual host is consuming bandwidth, which upstream is failing, or which user agent dominates a given host. The same counters double as the input for traffic limits, so measurement and enforcement share one source.

Key capabilities

• vhost_traffic_status_zone defines the shared memory zone that holds all counters, and vhost_traffic_status_dump writes statistics to disk so they survive a reload.
• vhost_traffic_status_display serves the current status, with vhost_traffic_status_display_format selecting the output format and vhost_traffic_status_display_jsonp enabling JSONP callbacks; vhost_traffic_status_display_sum_key controls the summed key.
• On-the-fly control of zones: status, reset, and delete operations are exposed for fully, group, and each zones, with separate JSON payloads used by status and by control.
• vhost_traffic_status_filter, vhost_traffic_status_filter_by_host, and vhost_traffic_status_filter_by_set_key break traffic down by custom keys, bounded by vhost_traffic_status_filter_max_node and deduplicated with vhost_traffic_status_filter_check_duplicate.
• Traffic limits via vhost_traffic_status_limit, vhost_traffic_status_limit_traffic, and vhost_traffic_status_limit_traffic_by_set_key, applied per server, per filter, or per upstream.
• Documented use cases for counting traffic by individual country through GeoIP, by storage volume, by user agent, by detailed HTTP status code, and by dynamic DNS, plus excluding the status page itself from the counts.
• A React Dashboard is provided for consuming the statistics, and the README documents customizing the module both before and after installation.

Who uses it and how

• Nginx operators running many virtual hosts on one instance who need per-host traffic figures without deploying a separate monitoring daemon.
• Teams using GeoIP to attribute traffic to individual countries, and teams attributing traffic to individual storage volumes or user agents.
• Operators who need a granular breakdown of detailed HTTP status codes per host, which plain aggregate counters do not provide.
• Sites that must keep statistics across restarts, using vhost_traffic_status_dump to persist data permanently rather than losing counters on reload.
• Environments that enforce traffic ceilings per server, per filter key, or per upstream, using the limit directives against the same counters they report.

Getting started

The README provides an Installation section and a Synopsis. Installation is a build step against Nginx source; no package name, Docker image, or compose file is documented in the facts provided, so the module is compiled and enabled through the vhost_traffic_status_zone and vhost_traffic_status directives.

How it compares

No list of paid products that this project replaces is provided in the facts, and no similar tools are named. It stands alone in this registry.

When to use it — and when not to

A self-hoster must operate an Nginx build toolchain, since the module is compiled in rather than dropped in as a standalone service, and counters live in a shared memory zone whose contents are lost on reload unless vhost_traffic_status_dump is configured. Anyone who needs a vendor-packaged binary, a container image, or coverage of non-Nginx workloads should not pick it. The README is extensive but is organised largely as a directive reference, so the facts give no published version number and no packaged distribution path.

shell> git clone git://github.com/vozlt/nginx-module-vts.git

shell> pwd
/somewhere/nginx
shell> CC=gcc ./auto/configure --with-cc-opt='-fprofile-generate -fprofile-dir=./objs' --with-ld-opt='-lgcov' --add-module=/somewhere/nginx-module-vts
shell> make

shell> pwd
/somewhere/nginx-module-vts
shell> sudo PATH=/somewhere/nginx/objs:$PATH prove -r t/000.display_html.t
...(during runtime it records coverage data into .gcda files)

shell> pwd
/somewhere/nginx
shell> CC=gcc ./auto/configure --with-cc-opt='-fprofile-use -fprofile-dir=/somewhere/nginx-module-vts/objs' --with-ld-opt='-lgcov' --add-module=/somewhere/nginx-module-vts
shell> make

http {
    vhost_traffic_status_zone;

    ...

    server {

        ...

        location /status {
            vhost_traffic_status_display;
            vhost_traffic_status_display_format html;
        }
    }
}