ngxtop: Open Source Monitoring & Observability

What is ngxtop?

ngxtop is a command-line tool that parses an nginx access log and prints top-like, real-time metrics about what a server is serving at that moment, built for engineers who need to troubleshoot or watch a live nginx instance without standing up a monitoring stack.

What it is

ngxtop is a Python package, installed from PyPI, that reads an nginx access log and produces a continuously refreshed report of request activity. It runs on a terminal, refreshes on an interval, and presents the same shape of output that operators already know from the top command: a summary line followed by a ranked table of the busiest request paths. By default it tries to determine the correct location and format of the nginx access log on its own, so a bare ngxtop invocation is enough to start watching traffic. It is not restricted to nginx, and it is not restricted to the default view; the log source, the log format, the grouping key, the filter, and the ordering are all configurable from the command line.

The concrete problem it solves is the gap between raw access log lines and an answer. When a site is slow or returning errors, the log file already contains the evidence, but reading it means either tailing and grepping by hand or writing a throwaway awk pipeline, and neither tells the operator what is happening right now in a form that can be scanned in seconds. ngxtop replaces that ad-hoc log wrangling with a purpose-built viewer that aggregates as the log grows, splitting counts across status classes such as 2xx, 3xx, 4xx, and 5xx and reporting average bytes sent alongside request counts.

Key capabilities

Parses access logs in combined (the default), common, and caddy formats, the last one handling Caddy JSON access logs.
Accepts an explicit log path with -l / --access-log and a format string with -f / --log-format matching the log_format directive in nginx configuration.
Detects the log format and location from an nginx config file when given -c / --config.
Defaults to follow mode, ignoring lines already in the log and reporting only new ones; --no-follow processes the existing content instead.
Supports the subcommands print, top, avg, sum, and info, so the same data can be queried several ways.
Groups and shapes output through -g / --group-by (default request_path), -o / --order-by (default count), -n / --limit (default 10), and -w / --having (default 1).
Adds computed columns with -a for aggregation expressions such as sum, avg, min, and max, and narrows records with -i / --filter or -p / --pre-filter.

Who uses it and how

Operators troubleshooting a single nginx server in a short window, the way they would reach for top on a busy host.
Teams investigating a traffic spike or an error burst: ngxtop top remote_addr ranks the client addresses generating the most requests.
Administrators tracking per-path load, using the default request_path grouping to see which URLs dominate the request count and how many of each fall into the 4xx and 5xx buckets.
Environments where the log is not local to the tool: the README describes parsing remote Apache common access logs, and the caddy format covers JSON access logs from Caddy.
Anyone who wants a quick read on request rate, expressed in the report as requests per second over the running interval.

Getting started

Install from PyPI with pip install ngxtop, then run ngxtop, optionally passing -l for the access log path and -f for the format. The README notes the tool is primarily developed and tested on Python 2 while also supporting Python 3.

How it compares

The README explicitly frames ngxtop as a short-period tool comparable to top, and points readers who need a long-running monitoring process or who want webserver stats stored in an external monitoring or graphing system toward Luameter. It is therefore a point-in-time inspection utility rather than a long-term metrics store, and its caddy format support shows it is not confined to the nginx-only niche that its name suggests.

When to use it — and when not to

Choose ngxtop when the question is "what is this server doing right now" and the answer should arrive in a terminal within seconds; it keeps no database, writes no metrics to disk, and requires no agent, which is exactly why it cannot answer questions about last week. Teams that need retention, dashboards, alerting, or historical graphing should run a full monitoring system instead, as the README itself suggests. A self-hoster should also note the project's own caveat that development and testing centre on Python 2, with Python 3 supported but secondary, so anyone standardised on modern Python should verify behaviour before relying on it in a production workflow.

project readme (upstream, from github) — read inline

================================================================ `ngxtop` - real-time metrics for nginx server (and others)

ngxtop parses your nginx access log and outputs useful, top-like, metrics of your nginx server. So you can tell what is happening with your server in real-time.

``ngxtop`` is designed to run in a short-period time just like the ``top`` command for troubleshooting and monitoring
your Nginx server at the moment. If you need a long running monitoring process or storing your webserver stats in external
monitoring / graphing system, you can try `Luameter `_.

ngxtop tries to determine the correct location and format of nginx access log file by default, so you can just run ngxtop and having a close look at all requests coming to your nginx server. But it does not limit you to nginx and the default top view. ngxtop is flexible enough for you to configure and change most of its behaviours. You can query for different things, specify your log and format, even parse remote Apache common access log with ease. See sample usages below for some ideas about what you can do with it.

Installation

pip install ngxtop

Note: ngxtop is primarily developed and tested with python2 but also supports python3.

Usage

Usage:
    ngxtop [options]
    ngxtop [options] (print|top|avg|sum) 
    ngxtop info

Options:
    -l , --access-log   access log file to parse.
    -f , --log-format   log format as specify in log_format directive.
    --no-follow  ngxtop default behavior is to ignore current lines in log
                     and only watch for new lines as they are written to the access log.
                     Use this flag to tell ngxtop to process the current content of the access log instead.
    -t , --interval   report interval when running in follow mode [default: 2.0]

    -g , --group-by   group by variable [default: request_path]
    -w , --having   having clause [default: 1]
    -o , --order-by   order of output for default query [default: count]
    -n , --limit   limit the number of records included in report for top command [default: 10]
    -a  ..., --a  ...  add exp (must be aggregation exp: sum, avg, min, max, etc.) into output

    -v, --verbose  more verbose output
    -d, --debug  print every line and parsed record
    -h, --help  print this help message.
    --version  print version information.

    Advanced / experimental options:
    -c , --config   allow ngxtop to parse nginx config file for log format and location.
    -i , --filter   filter in, records satisfied given expression are processed.
    -p , --pre-filter  in-filter expression to check in pre-parsing phase.

    Supported log formats: combined (default), common, caddy (for Caddy JSON access logs)

Samples

Default output


::

    $ ngxtop
    running for 411 seconds, 64332 records processed: 156.60 req/sec

    Summary:
    |   count |   avg_bytes_sent |   2xx |   3xx |   4xx |   5xx |
    |---------+------------------+-------+-------+-------+-------|
    |   64332 |         2775.251 | 61262 |  2994 |    71 |     5 |

    Detailed:
    | request_path                             |   count |   avg_bytes_sent |   2xx |   3xx |   4xx |   5xx |
    |------------------------------------------+---------+------------------+-------+-------+-------+-------|
    | /abc/xyz/xxxx                            |   20946 |          434.693 | 20935 |     0 |    11 |     0 |
    | /xxxxx.json                              |    5633 |         1483.723 |  5633 |     0 |     0 |     0 |
    | /xxxxx/xxx/xxxxxxxxxxxxx                 |    3629 |         6835.499 |  3626 |     0 |     3 |     0 |
    | /xxxxx/xxx/xxxxxxxx                      |    3627 |        15971.885 |  3623 |     0 |     4 |     0 |
    | /xxxxx/xxx/xxxxxxx                       |    3624 |         7830.236 |  3621 |     0 |     3 |     0 |
    | /static/js/minified/utils.min.js         |    3031 |         1781.155 |  2104 |   927 |     0 |     0 |
    | /static/js/minified/xxxxxxx.min.v1.js    |    2889 |         2210.235 |  2068 |   821 |     0 |     0 |
    | /static/tracking/js/xxxxxxxx.js          |    2594 |         1325.681 |  1927 |   667 |     0 |     0 |
    | /xxxxx/xxx.html                          |    2521 |          573.597 |  2520 |     0 |     1 |     0 |
    | /xxxxx/xxxx.json                         |    1840 |          800.542 |  1839 |     0 |     1 |     0 |

View top source IPs of clients

$ ngxtop top remote_addr
running for 20 seconds, 3215 records processed: 159.62 req/sec

top remote_addr
| remote_addr     |   count |
|-----------------+---------|
| 118.173.177.161 |      20 |
| 110.78.145.3    |      16 |
| 171.7.153.7     |      16 |
| 180.183.67.155  |      16 |
| 183.89.65.9     |      16 |
| 202.28.182.5    |      16 |
| 1.47.170.12     |      15 |
| 119.46.184.2    |      15 |
| 125.26.135.219  |      15 |
| 125.26.213.203  |      15 |

List 4xx or 5xx responses together with HTTP referer


::

    $ ngxtop -i 'status >= 400' print request status http_referer
    running for 2 seconds, 28 records processed: 13.95 req/sec

    request, status, http_referer:
    | request   |   status | http_referer   |
    |-----------+----------+----------------|
    | -         |      400 | -              |

Parse apache log from remote server with `common` format

$ ssh user@remote_server tail -f /var/log/apache2/access.log | ngxtop -f common
running for 20 seconds, 1068 records processed: 53.01 req/sec

Summary:
|   count |   avg_bytes_sent |   2xx |   3xx |   4xx |   5xx |
|---------+------------------+-------+-------+-------+-------|
|    1068 |        28026.763 |  1029 |    20 |    19 |     0 |

Detailed:
| request_path                             |   count |   avg_bytes_sent |   2xx |   3xx |   4xx |   5xx |
|------------------------------------------+---------+------------------+-------+-------+-------+-------|
| /xxxxxxxxxx                              |     199 |        55150.402 |   199 |     0 |     0 |     0 |
| /xxxxxxxx/xxxxx                          |     167 |        47591.826 |   167 |     0 |     0 |     0 |
| /xxxxxxxxxxxxx/xxxxxx                    |      25 |         7432.200 |    25 |     0 |     0 |     0 |
| /xxxx/xxxxx/x/xxxxxxxxxxxxx/xxxxxxx      |      22 |          698.727 |    22 |     0 |     0 |     0 |
| /xxxx/xxxxx/x/xxxxxxxxxxxxx/xxxxxx       |      19 |         7431.632 |    19 |     0 |     0 |     0 |
| /xxxxx/xxxxx/                            |      18 |         7840.889 |    18 |     0 |     0 |     0 |
| /xxxxxxxx/xxxxxxxxxxxxxxxxx              |      15 |         7356.000 |    15 |     0 |     0 |     0 |
| /xxxxxxxxxxx/xxxxxxxx                    |      15 |         9978.800 |    15 |     0 |     0 |     0 |
| /xxxxx/                                  |      14 |            0.000 |     0 |    14 |     0 |     0 |
| /xxxxxxxxxx/xxxxxxxx/xxxxx               |      13 |        20530.154 |    13 |     0 |     0 |     0 |

Parse Caddy server access log with JSON format


::

    $ ngxtop -l /var/log/caddy/access.log -f caddy
    running for 15 seconds, 234 records processed: 15.60 req/sec

    Summary:
    |   count |   avg_bytes_sent |   2xx |   3xx |   4xx |   5xx |
    |---------+------------------+-------+-------+-------+-------|
    |     234 |         5482.342 |   198 |    12 |    22 |     2 |

    Detailed:
    | request_path                        |   count |   avg_bytes_sent |   2xx |   3xx |   4xx |   5xx |
    |-------------------------------------+---------+------------------+-------+-------+-------+-------|
    | /api/v1/users                       |      32 |          128.000 |    32 |     0 |     0 |     0 |
    | /images/logo.png                    |      28 |        24560.000 |    28 |     0 |     0 |     0 |
    | /blog/article-not-found             |      22 |         5621.000 |     0 |     0 |    22 |     0 |
    | /audiobooks                         |      21 |        16818.000 |    21 |     0 |     0 |     0 |
    | /v1/sessions/12345                  |      18 |           35.000 |    18 |     0 |     0 |     0 |
    | /static/css/main.css                |      17 |         1459.000 |    17 |     0 |     0 |     0 |

Frequently asked questions

Is ngxtop free to use?

ngxtop is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does ngxtop do?

Real-time metrics for nginx server

What is ngxtop written in?

ngxtop is primarily written in Python. Its source is publicly available at https://github.com/lebinh/ngxtop, and it has 6,525 GitHub stars.