VARNISHSTAT(1)

🎀 VARNISHSTAT ✨

okay bestie, gather round, because this is the varnishstat(1) page from your friendly neighbourhood General Commands Manual (section 1, obviously) and it's about to be your new obsession. 💖

---

✨ NAME ✨

varnishstat — Varnish Cache statistics 👑

---

🦋 SYNOPSIS 🦋

varnishstat [-1] [-c] [-f <glob>] [-h] [-I <glob>] [-j] [-l] [-n
<workdir>] [-r] [-t <seconds|off>] [-V] [-X <glob>] [-x]

---

🌸 DESCRIPTION 🌸

the varnishstat utility shows you the statistics from a varnishd(1) instance that's currently running. like, it's literally peeking at the numbers your cache is doing in real time. no cap. 📊

the following options are available:

• -1 — instead of doing the whole continuously-updated display thing, it just prints the stats to stdout. this is the default when standard output is being redirected. 💅
• -c — gives you a continuously updated, interactive display. this is the default when the standard output isn't redirected. main character behaviour fr.
• -f <glob> — a legacy field filtering glob. use a backslash to escape characters. if the argument starts with '^' it gets used as an exclusive glob. you can pass multiple -f arguments. legacy filtering globs run along with inclusion globs (-I arguments) and exclusion globs (-X arguments) in order on a first-match basis. 🫶
• -h — print the program usage and dip. bye! 👋
• -I <glob> — field inclusion glob. use a backslash to escape characters. multiple -I arguments are allowed. exclusion globs are run in order along with exclusion globs (-X arguments) and legacy filtering globs (-f arguments) on a first-match basis. 🌈
• -j — print the statistics to stdout as JSON. for the json girlies. 💜
• -l — lists all the available fields you can use with the -f option. window shopping, but for counters. 🛍️
• -n <workdir> — specify the varnish working directory of the instance you wanna attach to. peep the varnishd(1) -n option docs for the extra info and the defaults. 📁
• -r — toggle between raw and adjusted gauges. adjusted is the default. ⚖️
• -t <seconds|off> — timeout before it returns an error on the initial VSM connection. if you set it, the VSM connection gets retried every 0.5 seconds for that many seconds. if it's zero, the connection is only attempted once and will fail immediately if it doesn't work out. if it's set to "off", the connection will not fail — so the utility can start up and wait indefinitely for the Varnish instance to show up. defaults to 5 seconds. ⏰
• -V — print version information and exit. 🏷️
• -X <glob> — field exclusion glob. use a backslash to escape characters. multiple -X arguments are allowed. exclusion globs are run in order along with inclusion globs (-I arguments) and legacy filtering globs (-f arguments) on a first-match basis. 🚫
• -x — print the statistics to stdout as XML. retro vibes, honestly. ✨
• --optstring — prints the optstring parameter to getopt(3) to help you write wrapper scripts. lowkey a lifesaver for scripting besties. 🧚

---

🔮 CURSES MODE 🔮

when you don't pass -1, -j or -x, the application boots up in curses mode. this gives you a continuously updated view of the counter values, plus their descriptions. it's giving dashboard. 👑

• the top area shows process uptime information. ⏱️
• the center area shows a list of counter values. 📜
• the bottom area shows the description of whichever counter is currently selected. 🔍

on startup, only counters at INFO level are shown. 💅

📊 Columns 📊

these are the columns displayed, from left to right:

• Name — the name of the counter. 🏷️
• Current — the current value of the counter. 📍
• Change — the average per second change over the last update interval. 📈
• Average — the average value of this counter over the runtime of the Varnish daemon, or over a period if the counter can't be averaged. 🧮
• Avg_10 — the moving average over the last 10 update intervals. 🔟
• Avg_100 — the moving average over the last 100 update intervals. 💯
• Avg_1000 — the moving average over the last 1000 update intervals. 🚀

🎹 Key bindings 🎹

• <h> — toggle the help screen. 🆘
• <UP> or <k> — navigate the counter list one line up. ⬆️
• <DOWN> or <j> — navigate the counter list one line down. ⬇️
• <PAGEUP> or <b> or <CTRL-B> — navigate the counter list one page up. 📄
• <PAGEDOWN> or <SPACE> or <CTRL-F> — navigate the counter list one page down. 📃
• <HOME> or <g> — navigate the counter list to the top. 🔝
• <END> or <G> — navigate the counter list to the bottom. 🔚
• <d> — toggle between showing and hiding unseen counters. unseen counters are those that have been zero for the entire runtime of varnishstat. defaults to hiding unseen counters. 🙈
• <r> — toggle between showing raw and adjusted gauges. when a gauge gets decremented faster than it's incremented, it may show up as a large integer with its most significant bit set. by default, such values are adjusted to zero. 💅
• <e> — toggle scaling of values. 📐
• <v> — increase verbosity. defaults to only showing informational counters. 🗣️
• <V> — decrease verbosity. defaults to only showing informational counters. 🤫
• <q> — quit. 🏃
• <CTRL+T> — sample now. 📸
• <0> — reset averages. 🔄
• <+> — increase refresh interval. ➕
• <-> — decrease refresh interval. ➖

---

💾 OUTPUTS 💾

the XML output format is:

<varnishstat timestamp="YYYY-MM-DDTHH:mm:SS">
  <stat>
    <name>FIELD NAME</name>
    <value>FIELD VALUE</value>
    <flag>FIELD SEMANTICS</flag>
    <format>FIELD DISPLAY FORMAT</format>
    <description>FIELD DESCRIPTION</description>
  </stat>
  [..]
</varnishstat>

the JSON output format is:

{
  "timestamp": "YYYY-MM-DDTHH:mm:SS",
  "FIELD NAME": {
    "description": "FIELD DESCRIPTION",
    "flag": "FIELD SEMANTICS", "format": "FIELD DISPLAY FORMAT",
    "value": FIELD VALUE
  },
  "FIELD NAME": {
    "description": "FIELD DESCRIPTION",
    "flag": "FIELD SEMANTICS", "format": "FIELD DISPLAY FORMAT",
    "value": FIELD VALUE
  },
  [..]
}

Timestamp is the time when the report was generated by varnishstat. 🕰️

---

👀 SEE ALSO 👀

• varnishd(1)
• varnishhist(1)
• varnishlog(1)
• varnishncsa(1)
• varnishtop(1)
• curses(3)
• varnish-counters(7)

---

🫶 AUTHORS 🫶

this manual page was written by Dag-Erling Smørgrav, Per Buer, Lasse Karstensen and Martin Blix Grydeland. absolute icons, the whole squad. 👑

---

and that's the whole varnishstat(1) page bestie, straight from section 1 of the General Commands Manual — go forth and read your counters, you ate 💅✨🌸