nginx-module-vts: 25 directives, and a version row that slips
Nginx virtual host traffic status module
At a glance
- What is it?
- nginx-module-vts keeps per-virtual-host traffic counters inside the nginx process and exposes them through a status page, a JSON endpoint, filters and limits. The module is compiled into nginx rather than loaded, its test suite needs port 80 and therefore root, and its compatibility table lists a version under the wrong heading.
- Who is it for?
- nginx-module-vts fits an operator who wants per-site traffic numbers without shipping request logs to a collector, and it has the virtue of counting in the process that already sees every request. Two things to weigh before you rely on it.
- Can I use it commercially?
- Yes. BSD-2-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 5 days ago.
- What is it written in?
- Mainly C, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- vozlt/nginx-module-vts3,499 ★ · -5
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| vozlt/nginx-module-vts | 3.5k | 3.5k |
-5 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
You rebuild nginx to get this module
The installation is four steps and none of them is loading a file.
Clone the repository, add the module to the build configuration with the module flag pointing at the path, build the nginx binary, and install that binary. There is no dynamic load path and no package to install, because this is a static module: it becomes part of the server executable.
That single fact governs everything else about this project. Upgrading nginx means rebuilding it with the module again, and a server that must be rebuilt to gain a status page is a different kind of decision from adding a shared library. The module's own version, by contrast, is tracked as tags, and the readme points at the releases page for the latest one rather than hard-coding a number.
One detail in the clone command is worth a note. It uses the git protocol rather than the encrypted one, while every other link in the same document, including the badges and the release links, uses the encrypted form. If your network or your host refuses the older protocol, that one line is the part that fails, and switching it to the encrypted form is the fix.
The only listed dependency is nginx itself, which is the honest answer for a module with a build flag and no library.
The compatibility table names one version under the wrong heading
The version support section is a list of fourteen nginx lines, each with the version that was last tested against it. Reading it is instructive.
The newest line listed is 1.30, tested at 1.30.4, then 1.27 tested at 1.27.3, then 1.22, 1.19, 1.18, and so on down to 1.4 tested at 1.4.7. Earlier versions are stated not to be tested.
Two things stand out. First, there are gaps: the list jumps from 1.30 to 1.27, so the 1.29 and 1.28 lines are simply absent rather than marked unsupported. A reader cannot tell whether they were never tested or deliberately skipped.
Second, and more concretely, the row for 1.16 lists 1.15.1 as its last tested version. That version belongs to the 1.15 row directly underneath it, which lists 1.15.0. So one row's last-tested value has been copied from its neighbour.
Neither of these is a crisis. A table like this is maintained by hand and this one spans fifteen years of nginx releases, so a slip is expected. But the table is the only compatibility statement in the repository, and it is the thing you consult when deciding whether an nginx upgrade will break your traffic counters. Cross-check the release notes before you rebuild a server on the strength of one row.
Twenty-five directives, and their names describe the whole model
The directives section lists twenty-five directives, and reading them as families explains what this module actually does.
One declares the zone where counters live. Several deal with display: showing the status page, choosing its format, wrapping it as JSONP for cross-origin reads, and choosing which key the summary sums on. Another dumps the counters.
Then the filter family. You turn filtering on, restrict it by host or by a set key, ask it to reject duplicates, and cap it with a maximum node count. That last pair is the interesting one: the module is telling you that filters are nodes in a list, that duplicates are checked, and that the list can be bounded.
Then the limit family, which mirrors the filter family almost exactly: a limit directive, a limit on traffic, a limit by set key, a duplicate check, and two bypass switches, one for the limit and one for the statistics. The symmetry is deliberate. A filter defines a set of requests you care about, and a limit acts on such a set, so the two families need the same parameters.
The remaining directives cover the bridge between the two: setting by filter, choosing an averaging method, defining histogram buckets, and reporting statistics per upstream.
So the design is: count everything into a zone, filter into named sets, act on sets, and expose the result. Twenty-five directives is what that takes.
Traffic can be limited at three different scopes
The limit section is organised by where the limit applies, and there are three answers.
The first is per server, which is the virtual host itself. The second is per filter, which is the interesting case: a limit attached to a filter definition rather than to a location means the limit follows a set of requests wherever they appear. The third is per upstream, which applies the limit to a backend rather than to the client-facing side.
That middle scope is what makes the filter family worth having. Without it you could only rate-limit whole sites; with it you can define a set by something like user agent or status code and limit that set while leaving the rest of the traffic alone.
The document also lists the parameters that make the counters meaningful rather than merely accumulated. There is a directive choosing an averaging method, so a rate can be computed over an interval rather than as a running total, and a directive defining histogram buckets, so the module can report a distribution rather than a sum. Combined with a section on calculations and intervals in the table of contents, that tells you the module keeps more than one counter per set.
The two bypass directives are the escape hatches: one to ignore limits and one to ignore statistics, presumably for the status endpoint itself and for health checks.
Control is three operations across three scopes
The largest part of the table of contents is the control interface, and it is nine sections long.
There are three operations: get the status of traffic zones on the fly, reset them, and delete them. Each operation comes at three levels of granularity: all zones, groups of zones, and individual zones. That is three by three, and the readme gives each combination its own heading.
The design reason is that counters live in the server's memory and a long-running process accumulates them indefinitely. Without a reset, an average computed over an interval would be meaningless, and without a delete, a zone for a server name that no longer exists would keep its counters. So the control interface is not an extra, it is what makes the counters usable.
Getting and setting are told apart, and the document has separate sections for the JSON used by the status read and the JSON used by the control calls. That separation matters if you plan to script it: the read format and the write format are two contracts, not one.
There is also a section for setting traffic by filter, which is how you would seed a counter or adjust a set from outside the process.
The tests need port 80, and the PGO recipe uses them as the profile
Two operational details in this repository are worth reading together.
The first is the test command. After installing the module you run the test suite with a Perl test runner, recursively, and the readme says elevated privileges are required because the tests need nginx to listen on port 80. So the test suite binds a privileged port, which is why a developer runs it as root, and which is also why it cannot run in a container without that port free.
The second is the profile-guided optimisation recipe, which is offered with the phrase use at your own risk and a reference to a section of a paper rather than to documentation.
The recipe has three steps: configure with a compiler flag that generates profile data, run the tests so the generated binary records what it executes, then configure again with the flag that uses the profile.
CC=gcc ./auto/configure --with-cc-opt='-fprofile-generate -fprofile-dir=./objs' --with-ld-opt='-lgcov' --add-module=/somewhere/nginx-module-vtsThe interesting part is step two, and the readme is explicit about it: it runs a single display test, and during the run the binary writes coverage data files.
So the entire optimisation profile of your web server comes from one test that renders a status page. That is not representative of production traffic, and the readme's own caution about it is warranted. The mechanism works; the workload is narrow.
The Makefile builds the dashboard, not the module
Look at the root of the repository and the division of labour is clear.
The module's own build is done by nginx's configure script, not by this repository. What the Makefile here does is build the web frontend: install its dependencies with the JavaScript package manager, build it for production into a distribution folder inside the frontend directory, start a development server with an API proxy pointing at a running module, and clean both the built output and the installed dependencies.
Four targets, all named for the frontend, all delegating to npm. So the module and its dashboard are two build systems in one repository, and only one of them has a make interface.
The tree is arranged the same way. A source directory, a test directory that corresponds to the recursive test command, a share directory, a utility directory, a configuration entry, and the frontend directory. There is also a configuration file for a changelog generator driven by commit messages, next to a generated changelog, which tells you the release notes are written by a tool reading history rather than by a person.
The continuous integration badge and a licence badge sit at the top of the readme, and the licence is the two-clause BSD variant.
Seven use cases are one counter read seven ways
The use cases section is the best argument for the module, because it shows what a per-host counter becomes when you combine it with filters.
Seven are listed. Traffic per country, using a geolocation database. Traffic per storage volume. Traffic per user agent. Traffic per detailed HTTP status code. Traffic per dynamic DNS name, which matters when one site answers on many addresses. Traffic excluding the status page itself, so your monitoring does not inflate the numbers it reports. And keeping statistics data permanently, which the table of contents places in its own section.
Each of those is one line of configuration on top of the same underlying set of counters. The geolocation case needs a lookup module rather than anything from this project; the user agent case needs a filter that matches a header. But the counting is identical.
The last one is the odd entry out, because it is about lifetime rather than dimension. Statistics that exist only in memory are gone when nginx restarts, which for a nightly reload is every few weeks on some deployments. A section devoted to making them survive tells you the author has hit that problem, and it is the one case where you should read the documentation before assuming the numbers you see are complete.
The remaining sections of the readme cover customising the build before and after installing the module, a separate React dashboard, the directive reference, releases, a see-also list and a to-do list.
Editorial conclusion
nginx-module-vts fits an operator who wants per-site traffic numbers without shipping request logs to a collector, and it has the virtue of counting in the process that already sees every request. Two things to weigh before you rely on it. The counters live in nginx's memory, which is why the document includes a control interface for resetting and deleting zones at runtime and a section on keeping statistics permanently. And the module is compiled in, so adopting it means rebuilding and redeploying the web server binary itself, not adding a file. The version list is the third thing: it is maintained by hand and one row already names the wrong version, so check the release notes rather than trusting the table when you plan an upgrade across nginx versions.
Frequently asked questions
What is nginx-module-vts?
A module for the nginx web server that keeps per-virtual-host traffic counters and exposes them. It has directives to declare a status zone, to display a report as HTML or JSON, to filter collected traffic into named sets, and to limit traffic at three scopes, plus a runtime control interface for resetting and deleting zones.
How do I install nginx-module-vts?
Clone the repository, add --add-module pointing at its path to nginx's build configuration, then build and install the nginx binary. The module is compiled into the server rather than loaded dynamically, and its only listed dependency is nginx itself.
How do I run the nginx-module-vts tests?
Run sudo prove -r t after installing the module. The elevated privileges are required because the test suite needs nginx to listen on port 80.
Which nginx versions does nginx-module-vts support?
The readme lists fourteen version lines with the version last tested on each, from 1.4.x up to 1.30.x, and states that earlier versions are not tested. The 1.30 line was last tested at 1.30.4, while the row for 1.16 names 1.15.1, which belongs to the 1.15 row.
What can nginx-module-vts measure?
Traffic per country using a geolocation database, per storage volume, per user agent, per detailed HTTP status code, and per dynamic DNS name. It can also exclude the status page from its own statistics and keep statistics permanently rather than only in memory.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/vozlt-nginx-module-vts)Star history chart for your README
[](https://hysenlabs.com/projects/vozlt-nginx-module-vts)Was this useful?