VARNISHTOP(1)

💖 VARNISHTOP(1) 💖

okay bestie, gather round — this is the manual page for varnishtop, living its best life in the General Commands Manual section of your friendly neighbourhood Unix box. It's giving "top, but for Varnish logs." 🎀

---

✨ NAME ✨

varnishtop — Varnish log entry ranking 👑

---

🌸 SYNOPSIS 🌸

varnishtop [-1] [-b] [-c] [-C] [-d] [-E] [-f] [-g
<session|request|vxid|raw>] [-h] [-i <taglist>] [-I <[taglist:]regex>]
[-L <limit>] [-n <workdir>] [-p <period>] [-Q <file>] [-q <query>] [-r
<filename>] [-t <seconds|off>] [-T <seconds>] [-x <taglist>] [-X
<[taglist:]regex>] [-V]

---

💅 DESCRIPTION 💅

So like, varnishtop reads the shared memory logs of varnishd(1) and serves you a continuously updated list of the log entries that show up the most. It's basically a leaderboard for your logs. 🔥

And if you filter it right with -I, -i, -X and -x, you can rank requested documents, clients, user agents, or literally anything else that got recorded in the log. main character energy for your log data. ✨

The following options are available:

🫶 OPTIONS 🫶

• -1 — instead of that always-refreshing live display, just print the stats once and dip. Lowkey implies -d too. 💀
• -b — only show transactions and log records that came from backend communication.
• -c — only show transactions and log records that came from client communication.
• -C — do all the regex and string matching caseless, no cap. (Case-insensitive, bestie.)
• -d — process log records at the head of the log.
• -E — display ESI transactions and other types of sub-requests. This implies -c and includes other client transactions too. 🌈
• -f — sort and group only on the first field of each log entry. For entries shaped like prefix: value, it's the prefix (sans colon) that gets sorted and grouped. Super useful when you're showing e.g. ReqStart entries, where that first field is the client IP address. 📍
• -g <session|request|vxid|raw> — how the log records get grouped. Default is grouping by vxid.
• -h — print program usage and exit. Short and sweet. ✌️
• -i <taglist> — include log records of these tags in the output. taglist is a comma-separated list of tag globs, and you can stack multiple -i options. 🎀

heads up: if a tag include option is the first of any tag selection options, then all tags are first marked excluded.

• -I <[taglist:]regex> — include by regex matching. Only outputs records matching taglist and the regular expression. Applies to any tag if taglist is absent. Multiple -I options may be given. 🔍

same deal: if a tag include option is the first of any tag selection options, all tags are first marked excluded.

• -L <limit> — sets the upper limit of incomplete transactions kept before the oldest transaction gets force completed. When that happens, a warning record is synthesized. This keeps an upper bound on the memory usage of running queries. Defaults to 1000 transactions. 🧠
• -n <workdir> — specify the varnish working directory of the instance to attach to. Peep the varnishd(1) -n option documentation for extra info and the defaults. 📂
• -p <period> — specifies the number of seconds to measure over; default is 60 seconds. The first number in the list is the average number of requests seen over this time period. This option does nothing if -1 is also used. ⏱️
• -Q <file> — specifies the file containing the VSL query to use. When multiple -Q or -q options are specified, all queries are treated as if the or operator was used to combine them. 📄
• -q <query> — specifies the VSL query to use. When multiple -q or -Q options are specified, all queries are treated as if the or operator was used to combine them. 💬
• -r <filename> — read log in binary file format from this file. You can make such a file with varnishlog -w filename. If the filename is -, logs are read from the standard input, and it cannot work as a daemon. 🦋
• -t <seconds|off> — timeout before returning an error on the initial VSM connection. If set, the VSM connection is retried every 0.5 seconds for this many seconds. If zero, the connection is attempted only once and will fail immediately if unsuccessful. If set to "off", the connection will not fail, letting the utility start and wait indefinitely for the Varnish instance to appear. Defaults to 5 seconds. ⏳
• -T <seconds> — sets the transaction timeout in seconds. This defines the max number of seconds elapsed between a Begin tag and the End tag. If the timeout expires, a warning record is synthesized and the transaction is force completed. Defaults to 120 seconds. ⌛
• -x <taglist> — exclude log records of these tags in output. taglist is a comma-separated list of tag globs. Multiple -x options may be given. 🚫
• -X <[taglist:]regex> — exclude by regex matching. Do not output records matching taglist and the regular expression. Applies to any tag if taglist is absent. Multiple -X options may be given. 🙈
• -V — print version information and exit. 👑
• --optstring — print the optstring parameter to getopt(3) to help when writing wrapper scripts. 🧚

---

🌟 EXAMPLES 🌟

This one gives you a continuously updated list of the most frequently requested URLs:

varnishtop -i ReqURL

And this one gives you a continuously updated list of the most commonly used user agents:

varnishtop -C -I ReqHeader:User-Agent

---

👀 SEE ALSO 👀

• varnishd(1)
• varnishhist(1)
• varnishlog(1)
• varnishncsa(1)
• varnishstat(1)

---

📜 HISTORY 📜

varnishtop was originally developed by Poul-Henning Kamp</> in cooperation with Verdens Gang AS and Varnish Software AS, and was later substantially rewritten by Dag-Erling Smørgrav</>. This manual page was written by Dag-Erling Smørgrav, and later updated by Martin Blix Grydeland. Iconic lineage honestly. 🫶

---

⚖️ COPYRIGHT ⚖️

This document is licensed under the same licence as Varnish itself. See LICENCE for details.

• Copyright (c) 2006 Verdens Gang AS
• Copyright (c) 2006-2015 Varnish Software AS

---

and that's the whole page bestie!! 💖 you've been reading VARNISHTOP(1) from the General Commands Manual — go rank some logs, you absolute legend, mwah 💅✨