Parse an Nginx Access Log for Top IPs, Paths, and Status Codes
You're staring at a two-gigabyte access.log after a traffic spike, or you want to confirm whether that one IP hammering your API is actually a problem or just a health-check cron. awk and grep work, but they get verbose fast and you end up writing a 14-line one-liner you'll never remember. This script does three specific things in under a second: top N client IPs, top N requested paths, and the full HTTP status-code distribution. No Python dependency. No jq. Just cut, sort, uniq, and head — all in the base Ubuntu image.
Here's the whole thing:
#!/usr/bin/env bash
set -euo pipefail
N=10
LOG=""
while getopts ":n:h" opt; do
case $opt in
n) N=$OPTARG ;;
h) echo "Usage: $0 [-n TOP_N] <access.log>"; exit 0 ;;
\?) echo "Error: unknown flag -${OPTARG}" >&2; exit 1 ;;
:) echo "Error: -${OPTARG} requires an argument" >&2; exit 1 ;;
esac
done
shift $((OPTIND - 1))
if [[ $# -ne 1 ]]; then
echo "Error: expected exactly one log file argument." >&2
echo "Usage: $0 [-n TOP_N] <access.log>" >&2
exit 1
fi
LOG=$1
[[ -f "$LOG" ]] || { echo "Error: '$LOG' is not a regular file." >&2; exit 1; }
[[ -s "$LOG" ]] || { echo "Error: '$LOG' is empty (0 bytes)." >&2; exit 1; }
echo "--- Top ${N} client IPs ---"
cut -d' ' -f1 "$LOG" | sort | uniq -c | sort -rn | head -n "$N"
echo
echo "--- Top ${N} requested paths ---"
cut -d' ' -f7 "$LOG" | sort | uniq -c | sort -rn | head -n "$N"
echo
echo "--- HTTP status-code distribution ---"
cut -d' ' -f9 "$LOG" | sort | uniq -c | sort -rn

What each section does and why it's there
set -euo pipefail — Non-negotiable in any script you'll run unattended. -e exits on the first non-zero return. -u treats unset variables as fatal errors, so a typo where you write $NO instead of $N kills the script immediately rather than silently passing an empty string to head and giving you zero rows with no explanation. -o pipefail makes the pipeline return the rightmost failed exit code instead of only the last command's status. Without it, if cut fails on a permissions issue but head succeeds with zero lines, you get exit 0 and no idea anything went wrong.
The getopts loop — Handles -n (top N, defaults to 10) and -h (prints usage). The leading colon in the optstring ":n:h" switches bash into silent-error mode: instead of the shell printing its own cryptic message for a bad flag, your \? case catches it and you get a clean one-liner on stderr. The :) case covers the situation where someone types -n without supplying a number. Both error paths write to stderr and exit 1, so a calling script or cron wrapper can detect the failure.
shift $((OPTIND - 1)) — After getopts finishes, $@ still contains the original flags. This shifts them off the argument list so that $1 is actually your log file path. Skipping this line is a common mistake; you end up treating -n as the filename and getting a "not a regular file" error.
The two file guards — [[ -f "$LOG" ]] rejects directories, character devices, and symlinks pointing at missing targets. [[ -s "$LOG" ]] catches the 0-byte file, which is what you get from a freshly rotated log that nginx hasn't written to yet. Both print a specific message to stderr and exit non-zero. You want hard failures here because this script is designed to run in cron or a CI step where silence means "all good."
The three report pipelines — Each one is the same structure with a different field number pulled from the standard combined log format:
- Field 1: client IP address
- Field 7: request path (from
"GET /index.html HTTP/1.1"you get/index.html) - Field 9: HTTP status code
cut -d' ' -fN extracts the column by space delimiter. sort | uniq -c counts how many times each value appears. sort -rn orders by count, highest first. head -n "$N" trims to your requested top N. The status-code section deliberately skips head because there are only about 20 distinct codes you'll ever see in practice; showing all of them is more useful than arbitrarily cutting the list at 10.
Verification
I ran this in a clean Ubuntu container against four test files covering normal data, an empty file, a malformed log with truncated lines, and a nonexistent path. All 10 assertions passed:
=== RUN: bash /work/parse_nginx.sh -n 3 /tmp/testdata/normal.log ===
PASS: normal: top IP is 192.168.1.10 (count 3)
PASS: normal: /index.html listed in paths
PASS: normal: status 404 present
=== RUN: bash /work/parse_nginx.sh /tmp/testdata/empty.log ===
PASS: empty: exit code is non-zero
PASS: empty: stderr mentions 'empty'
=== RUN: bash /work/parse_nginx.sh -n 100 /tmp/testdata/malformed.log ===
PASS: malformed: valid IP 192.168.1.10 still reported
PASS: malformed: status 301 appears in distribution
PASS: malformed: /a/b/c path captured
=== RUN: bash /work/parse_nginx.sh /tmp/testdata/nonexistent.log ===
PASS: missing: exit code is non-zero
PASS: missing: error mentions the filename
Results: 10 passed, 0 failed
The malformed-log test is the one that matters in production. If a line has fewer than nine fields — a truncated write, a reverse proxy that logged in a different format, a line split mid-write during a crash — cut returns an empty string for the missing field. The script doesn't crash. It reports whatever valid data is present and the blanks simply don't show up in the count. That's the behavior you want at 3 AM when you're trying to figure out why your 502 rate spiked.
Limitations, stated plainly
This assumes standard or combined log format with space-delimited fields. If you've customized log_format in your nginx.conf to insert extra columns before the path or status code, the field numbers shift and you'll get garbage output. Check your config first.
It does not strip IPv6 brackets. An entry like [2001:db8::1] will report as the string [2001:db8::1] rather than a clean address. For a mixed v4/v6 deployment, pipe through sed 's/^\[//; s/\]$//' before the cut.
The pipeline is streaming — it does not load the file into memory. A 50 GB log on a machine with 16 GB of RAM is fine. If you're running this on a Raspberry Pi with 1 GB of RAM and a 200 GB log, split the file first with split -l 500000 and run the script on each chunk.
How to use it
# Top 10 IPs, paths, and status codes from today's log
./parse_nginx.sh /var/log/nginx/access.log
# Only the top 3 — quick glance before you open a terminal session
./parse_nginx.sh -n 3 /var/log/nginx/access.log
# Pipe into less if your terminal is small
./parse_nginx.sh -n 20 /var/log/nginx/access.log | less
# Grab just the top IP for a monitoring cron
./parse_nginx.sh -n 1 /var/log/nginx/access.log 2>/dev/null | head -3 > /tmp/top_ip_today
Save it as parse_nginx.sh, run chmod +x on it, and drop it in the same directory as your logs. If you're already running Graylog or Loki for structured query, this is the 10-second check you do before firing up the dashboard. Sometimes you just need to confirm that 192.168.1.10 hit your endpoint four thousand times in the last hour, and you don't want to wait for a Kibana query to spin up.