--dashboard overviewOperations overview
A single-pane summary of request rates, traffic in/out, unique clients, HTTP status distribution, response-time percentiles, and busiest URLs. Start here when a reverse proxy behaves unexpectedly.

IPSONIC-ADCTOP turns live Nginx access logs into a colorful, keyboard-driven operations console. Follow throughput, investigate errors, identify noisy clients, and spot suspicious patterns — without a monitoring stack.

Nginx access logs are already recording what your edge is doing. ADCTOP turns that raw stream into an immediate operational picture: what changed, which URLs or clients dominate, whether failures are increasing, and where response time is being lost. No log shipping, cloud account, or monitoring infrastructure is needed to start asking useful questions.
Spot bandwidth spikes, unusually active IPs, changes in request mix, and the URLs consuming capacity. Move from a wall of access-log lines to a prioritized investigation.
Correlate 401/403/404/429 activity, scanning paths, user agents, and noisy clients during a live incident. Use the results as leads for deeper analysis, not as automatic threat verdicts.
Watch 5xx rates, redirects, API traffic and latency during deployments or troubleshooting. Check whether a fix improves behavior before opening a heavier analytics stack.
You already have Nginx logs. ADCTOP makes them actionable without shipping them elsewhere. Ideal for reverse proxies, load balancers, ADC nodes, web gateways, jump hosts, and operators who prefer a fast SSH session over another browser tab.
One Python 3 script. Standard-library parsing, terminal rendering, and keyboard input. No pip packages, agents, collectors, message queues, or database.
Track requests per second, traffic in and out, HTTP status classes, clients, methods, referers, user agents, and response times.
Review unusual clients, error-heavy URLs, suspicious paths, and crawler-like user agents. Heuristics are clues, not attack verdicts.
Stream access logs from another machine over a plain SSH pipe. Use FD 3 for the log stream and /dev/tty for reliable keyboard control.
Switch dashboards, investigate clients, apply filters, and cycle 60 retro and high-contrast themes — including wallboard and daylight styles.
No SaaS account, outbound telemetry, or external API required. Operate close to the logs on Debian, Ubuntu, AlmaLinux, Rocky Linux, and similar Linux hosts.
Authentic terminal captures: all 21 images were captured directly from IPSONIC-ADCTOP v0.3.4 running in xterm (160 × 48 characters, MEOW theme) under Xvfb, using 1,400 synthetic Nginx access-log records. They are not AI-generated or reconstructed interfaces. Metrics are illustrative test data.
Start a dashboard directly from the command line, or press d to cycle through all dashboards, then return to the nine-page table mode. URL lists use full-width rows in the focused dashboards.
RPS, bandwidth, unique clients, response-time percentiles, error trends, HTTP status distribution, top URLs, and referers.
Incoming and outgoing traffic, throughput, request volume, busiest URLs, and high-volume clients.
HTTP error rates, status distribution, top failing URLs, and clients associated with error traffic.
Successful responses, redirects, commonly requested healthy URLs, clients, and methods.
Top user-agent strings, associated requests, clients, URLs, and status behavior.
Referrer distribution, destination URLs, and clients. Optional grouping by referrer hostname.
P50, P95, and P99 response times, slow URLs, and clients with costly requests when request-time data is logged.
Most active IP addresses, request volume, bytes, and frequently requested URLs.
401/403/404/429 responses, probe-like paths, suspicious URLs, and clients worthy of closer inspection.
Bot-like user-agent patterns, associated requests, target URLs, and client activity.
API paths, methods, HTTP errors, request rates, and endpoint response times.
Latency buckets, slow requests, P95/P99 behavior, and URLs that may be hurting user experience.
Every image below was captured by running the actual IPSONIC-ADCTOP v0.3.4 Python/curses application in a 160 × 48 terminal with the meow theme and synthetic Nginx combined-log data. These are not mockups or AI-generated interfaces. Select any image for its original PNG.
--dashboard overviewA single-pane summary of request rates, traffic in/out, unique clients, HTTP status distribution, response-time percentiles, and busiest URLs. Start here when a reverse proxy behaves unexpectedly.

--dashboard trafficSee how many requests and bytes move through Nginx. Identify high-volume clients and URLs; use this view to investigate traffic spikes or unexpectedly large responses.

--dashboard errorsFocus on 4xx and 5xx response patterns, top failing URLs, status codes, and affected clients. Useful for separating application failures from rejected or missing requests.

--dashboard successAnalyze 2xx and 3xx responses separately from failures. Identify the most frequently requested healthy URLs, redirect behavior, methods, and clients.

--dashboard user-agentsRank user-agent strings and inspect the requests and clients associated with them. User-agent values are self-reported and can be forged.

--dashboard referrersInspect referring pages or hosts, the destinations they reach, and their relative request volume. Empty or missing referrers are normal for many clients.

--dashboard latencyReview response-time percentiles and slow URLs to identify bottlenecks. Requires request_time values in the access log for meaningful timing statistics.

--dashboard clientsRank source IP addresses by request count and transferred bytes, then inspect frequently requested paths. IP addresses may represent NAT gateways or proxies.

--dashboard securitySurface probe-like paths, denied responses, missing resources, and active clients. These are heuristics for triage, not a determination that a request is malicious.

--dashboard botsShow automation-like user-agent patterns, their request volume, target paths, and clients. This is classification by observed log patterns, not verified bot identity.

--dashboard apiConcentrate on API paths, HTTP methods, errors, and latency. Helpful when Nginx fronts REST APIs or acts as an application delivery controller.

--dashboard slaInspect slow-request counts, latency buckets, percentiles, and problematic URLs. This is an operational view, not a contractual SLA calculation.

Use keys 1–9 to open these tables immediately, or start a table with --page NUMBER. Tables provide focused ranking, sorting, and row selection.
--page 1Ranks requested URLs by request count, transferred bytes, and average response time. Useful for finding hotspots and expensive resources.

--page 2Ranks client IP addresses to expose heavy requesters and bandwidth consumers. IPs may be shared by many users behind a proxy.

--page 3Lists HTTP Referer values so you can identify traffic sources and unexpected referrer patterns.

--page 4Ranks reported User-Agent headers to distinguish common browsers, command-line clients, and crawler-like traffic.

--page 5Groups requests by exact HTTP status code, making shifts between successful, redirected, denied, and failed responses visible.

--page 6Breaks down GET, POST, HEAD, PUT, DELETE, and other request methods to understand workload behavior.

--page 7Shows the URLs producing client-error responses, including missing paths, access denials, and rate-limit responses.

--page 8Shows URLs associated with server-side errors; use this table to investigate upstream failures and application outages.

--page 9Ranks URLs by average request duration where Nginx request_time data is present; helps pinpoint slow endpoints.

request_time field.Deploy the Python source as a normal executable. The download is a standalone script — no archive extraction or package manager required.
curl -fL https://ipsonic.com/adctop/ipsonic-adctop.py -o ipsonic-adctop.py
sudo install -o root -g root -m 755 ipsonic-adctop.py /usr/local/bin/ipsonic-adctop ipsonic-adctop --version
ipsonic-adctop -d /var/log/nginx/access.log
Read one or more local access logs. Glob patterns let you monitor a group of virtual hosts without adding a log collector.
ipsonic-adctop -d '/var/log/nginx/*access.log'For a quick trial, use the interpreter without copying the script into /usr/local/bin.
python3 ipsonic-adctop.py -d access.logrequest_time=... and request_length=....ADCTOP accepts standard combined access-log records and optional trailing key/value fields. These extra fields improve latency and traffic metrics.
log_format adctop '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'request_length=$request_length request_time=$request_time';
access_log /var/log/nginx/access.log adctop;Nginx's $request_time is in seconds; ADCTOP reports response-time values in milliseconds. $body_bytes_sent represents outgoing response-body bytes, not total wire traffic.
Run tail -f on the remote host and stream its output into ADCTOP. Use ssh -n so SSH does not compete for local keyboard input.
user@adcipsonic-adctop --help to verify the command is available on the workstation where you want to see the dashboard.ssh user@adc 'hostname' and confirm you can connect to the Nginx host. For automated access, use SSH keys.sudo -n /usr/bin/tail -f /var/log/nginx/access.log (stop with Ctrl+C).q to quit. If log rotation replaces the file, restart the command or explicitly choose different tail behavior.The command reads logs over SSH without copying log files to disk. The remote host needs SSH, Nginx logs, and tail; the local host needs Python 3 and ADCTOP.
Configure this on the remote Nginx server (adc), not on the workstation. The account user may follow only the specified access log as root, without receiving general-purpose sudo rights.
command -v tail # Expected on many Linux systems: /usr/bin/tail
Use the exact absolute path reported by your server in both the sudoers rule and the remote SSH command.
sudo visudo -f /etc/sudoers.d/ipsonic-adctop
Insert the following single rule:
user ALL=(root) NOPASSWD: /usr/bin/tail -f /var/log/nginx/access.log
The sudoers entry matches the command and its arguments. It does not permit arbitrary tail options or paths. Do not use wildcards such as /usr/bin/tail * or NOPASSWD: ALL. Use a dedicated account and review log-data access according to your organization's policies.
# On adc: verify sudoers syntax and permissions sudo visudo -cf /etc/sudoers.d/ipsonic-adctop sudo chmod 0440 /etc/sudoers.d/ipsonic-adctop # On the workstation: test non-interactive remote access ssh -n user@adc 'sudo -n /usr/bin/tail -f /var/log/nginx/access.log' # Press Ctrl+C to stop after log lines appear
sudo -n? It prevents a hidden password prompt from blocking the log stream. If the sudoers rule is missing or mismatched, sudo fails immediately. The examples below use the full executable path to match the restricted rule exactly.tail -f still permits ongoing access to that log; treat it as a privileged data-read permission. tail -f follows the current file and may stop showing new requests after log rotation.ssh -n user@adc \
'sudo -n /usr/bin/tail -f /var/log/nginx/access.log' \
| ipsonic-adctop -d security --theme meow \
--input-fd 3 3<&0 0</dev/ttyssh -n prevents SSH from consuming local keystrokes. The pipe carries remote access-log lines to ADCTOP. 3<&0 duplicates the pipe onto file descriptor 3, and 0</dev/tty restores local terminal input so dashboard shortcuts work immediately. --input-fd 3 tells ADCTOP to read the log from that separate descriptor.ssh -n detaches SSH's stdin from the local terminal. This avoids competing keyboard readers in the pipeline.
FD 3 carries the remote log stream while standard input is redirected to the local terminal for interaction.
tail -f follows the current file descriptor. Unlike tail -F, it does not automatically follow a replaced file after rotation.
ssh -n user@adc \ 'sudo -n /usr/bin/tail -f /var/log/nginx/access.log' \ | ipsonic-adctop -d traffic
ssh -n user@adc \
'sudo -n /usr/bin/tail -f /var/log/nginx/access.log' \
| ipsonic-adctop --dashboard sla --theme wallboard \
--input-fd 3 3<&0 0</dev/ttysudo requires a password or an interactive TTY, configure appropriate access first. Avoid putting passwords into pipelines. For unattended use, a narrowly scoped sudoers rule for the required log-reading command is preferable to broad root access.The options below reflect the included v0.3.4 Python source. Run ipsonic-adctop --help for the built-in help text.
| Option | Purpose | Example |
|---|---|---|
LOGS... | Log paths, glob patterns, or - for stdin | /var/log/nginx/access.log |
-d [NAME], --dashboard [NAME] | Start in a named dashboard; defaults to overview when no name is supplied | -d security |
-p 1-9, --page 1-9 | Start in a numbered table view; mutually exclusive with -d | -p 9 |
--list-dashboards | Print all dashboard names | --list-dashboards |
--theme NAME | Choose initial color palette; default meow | --theme irix |
--list-themes | Print the available color palettes | --list-themes |
--input-fd FD | Read log lines from an inherited file descriptor | --input-fd 3 |
-w N, --window N | Sliding-window duration in seconds; default 60 | --window 300 |
-i N, --interval N | Refresh interval in seconds; default 0.5 | --interval 1 |
--from-start | Process existing log lines at startup using ingestion time | --from-start |
--top N | Maximum rows in each dashboard top list; default 5 | --top 10 |
--referer-domain | Group referrers by hostname | --referer-domain |
--dashboard-referer-exclude REGEX | Hide matching referrers in dashboard Top Referrers only; repeatable and case-insensitive | --dashboard-referer-exclude 'localhost' |
-V, --version | Show version and exit | --version |
-h, --help | Show usage and exit | --help |
ipsonic-adctop --dashboard overview /var/log/nginx/access.log ipsonic-adctop --dashboard errors /var/log/nginx/access.log ipsonic-adctop --dashboard security /var/log/nginx/access.log ipsonic-adctop --dashboard bots /var/log/nginx/access.log ipsonic-adctop --dashboard user-agents /var/log/nginx/access.log ipsonic-adctop --dashboard api --window 300 /var/log/nginx/access.log ipsonic-adctop --dashboard sla --top 10 /var/log/nginx/access.log ipsonic-adctop --page 9 /var/log/nginx/access.log
The input reader uses /dev/tty for reliable terminal interaction, even when the log stream arrives via a pipe or a separate file descriptor.
| Key | Action | Key | Action |
|---|---|---|---|
| d | Cycle dashboards → table mode → overview | T | Cycle color themes |
| 1–9 | Jump to numbered table views | q | Quit |
| / | Set inclusion filter | ! | Set blacklist filter |
| c | Clear inclusion filter | x | Clear blacklist |
| Space | Pause / resume | r | Reset collected statistics |
| + / - | Adjust time window | s | Cycle table sort mode |
| ↑ / ↓ | Select entries | PgUp / PgDn | Scroll lists |
| Enter | Drill into selected URL/client where available | Esc | Return from detail view |
1 URLs · 2 IPs · 3 Referrers · 4 User Agents · 5 Statuses · 6 Methods · 7 4xx · 8 5xx · 9 Slowest URLs.
Explore all 60 themes with lightweight HTML color samples (not screenshots). The sample values are illustrative. Press T to rotate themes without restarting.
--theme meow--theme turbo--theme amber--theme matrix--theme daylight--theme sgi--theme irix--theme amiga--theme workbench--theme norton--theme solar--theme wallboard--theme snow--theme graphite--theme fireplace--theme campfire--theme ocean--theme arctic--theme sunset--theme terminal--theme paper--theme copper--theme midnight--theme emerald--theme cobalt--theme crimson--theme lime--theme azure--theme ruby--theme sapphire--theme forest--theme signal--theme teletext--theme ceefax--theme prestel--theme minitel--theme ansi_bbs--theme bbs_ice--theme bbs_fire--theme dos_cga--theme dos_ega--theme ibm_mda--theme hercules--theme vt100--theme vt220--theme apple_ii--theme commodore64--theme zx_spectrum--theme atari_st--theme mac_classic--theme mono_black--theme mono_white--theme phosphor_blue--theme phosphor_red--theme noc_red--theme noc_green--theme noc_blue--theme high_vis--theme sepia--theme lavenderipsonic-adctop --list-themes ipsonic-adctop -d traffic --theme wallboard /var/log/nginx/access.log
No. ADCTOP is an interactive access-log analyzer. Security and bot views are useful operational hints, not definitive detection or prevention.
No. The console reads files or incoming log streams directly. Nothing requires a hosted backend, an account, or external telemetry.
Nginx combined logs do not include request time by default. Add the optional request_time field to enable those measurements.
For remote streams, tail -f follows the open file. Reopen or restart the stream after rotation if needed. Use tail -F only when replacement-following behavior is desired.
Fail2ban monitors log messages and can temporarily ban addresses when a configured filter and jail detect repeated failures. IPSONIC-ADCTOP complements that workflow: press F to inspect suggested Fail2ban failregex patterns while you investigate live Nginx traffic. No Fail2ban installation is required to view suggestions in ADCTOP.
Start in the Security dashboard. Review 401, 403, 404 and 429 responses, frequently requested paths and the clients associated with them. A single HTTP error does not establish abuse.
Open four read-only regex candidates. Keys 1–4 select a suggestion; Esc or F returns to the monitoring screen. ADCTOP does not create filter files or modify jails.
Save and test a candidate against representative access logs using fail2ban-regex. Adjust the expression, exceptions and jail thresholds to avoid banning legitimate visitors.
A candidate matching the most frequent URL with status 401, 403, 404 or 429 in ADCTOP's current event window. The URL path is regex-escaped.
A generic candidate for Nginx requests returning 401 or 403. A 403 can be normal access control, so do not assume every match warrants a ban.
A candidate for 404 responses. Ordinary broken links and search-engine crawlers can generate many 404s; consider specific paths rather than banning all 404s.
A candidate for 429 responses, useful when Nginx already applies request-rate limits. Verify that the logged address is the real client.
This is an illustrative starting point for a conventional Nginx combined access log with the client IP at the beginning of the line. It is not a production-ready universal filter.
[Definition] failregex = ^<HOST> - .*?\[[^\]]+\] "[A-Z]+ [^"]+ HTTP/[0-9.]+" 429 ignoreregex =
sudo fail2ban-regex /var/log/nginx/access.log /etc/fail2ban/filter.d/ipsonic-nginx-429.conf
Inspect the match counts and unmatched examples. Test known legitimate traffic as well as suspicious samples. If you use a custom Nginx log_format, reverse proxy, IPv6 address format, or additional fields, adapt the regex before deployment.
Only after validating the filter, a Linux administrator can configure a Fail2ban jail. The following is a configuration example, not an ADCTOP command:
[ipsonic-nginx-429] enabled = false filter = ipsonic-nginx-429 logpath = /var/log/nginx/access.log findtime = 10m maxretry = 10 bantime = 10m
It is deliberately enabled = false. Review allowlists, the server's real client IP handling, firewall backend and operational impact before enabling a jail. Fail2ban is an optional external system; ADCTOP itself still uses only the Python standard library.