Allow to print CPU usage, memory & swap, load average, net I/O metrics in Tmux status bar
You might checkout tmux-config repo to see this plugin in action.
- CPU usage
- Memory available/free, used, total (KiB,MiB,GiB), free/used %
- Swap used, free, total, free/used %
- load average for last 1,5,15 minutes
- configurable thresholds (low, medium, stress) with custom colors
- tweak each metric output using templates (e.g, 'used 10% out of 16G')
- configurable size scale (K,M,G)
- OSX, Linux support
- TODO: network I/O metric support
Tested on: OS X El Capitan 10.11.5, Ubuntu 14 LTS, CentOS 7, FreeBSD 11.1.
Best installed through Tmux Plugin Manager (TMP). Add following line to your .tmux.conf file:
set -g @plugin 'samoshkin/tmux-plugin-sysstat'
Use prefix + I from inside tmux to install all plugins and source them. If you prefer, same effect can be achieved from command line:
$ ~.tmux/plugins/tpm/bin/install_plugins
Once plugged in, tmux status-left or status-right options can be configured with following placeholders. Each placeholder will be expanded to metric's default output.
#{sysstat_cpu}, CPU usage -CPU:40.2%#{sysstat_mem}, memory usage -MEM:73%#{sysstat_swap}, swap usage -SW:66%#{sysstat_loadavg}, system load average -0.25 0.04 0.34
For example:
set -g status-right "#{sysstat_cpu} | #{sysstat_mem} | #{sysstat_swap} | #{sysstat_loadavg} | #[fg=cyan]#(echo $USER)#[default]@#H"
You can change default output for CPU and memory metrics, if you need more fields to show, or you want to provide custom template. In your .tmux.conf:
For example, to get Used 4.5G out of 16G output for memory metric:
set -g @sysstat_mem_view_tmpl '#Used [fg=#{mem.color}]#{mem.used}#[default] out of #{mem.total}'
If you don't want CPU: prefix and don't like colored output for CPU metric:
set -g @sysstat_cpu_view_tmpl '#{cpu.pused}'
As you can see, each metric can be configured with template, containing fixed text (CPU:), color placeholder (#[fg=#{mem.color}]) and field placeholder (#{mem.used}). This approach gives you the ultimate control over the output for each metric. Following field placeholders are supported:
| CPU | |
|---|---|
#{cpu.color} |
main metric color |
#{cpu.pused} |
CPU usage percentage |
| Memory | |
|---|---|
#{mem.color} |
main metric color |
#{mem.free} |
free/available memory |
#{mem.pfree} |
free memory percentage against total |
#{mem.used} |
used memory |
#{mem.pused} |
used memory percentage against total |
#{mem.total} |
total installed memory |
| Swap | |
|---|---|
#{swap.color} |
main swap metric color |
#{swap.free} |
free swap memory |
#{swap.pfree} |
free swap memory percentage against total swap space |
#{swap.used} |
used swap memory |
#{swap.pused} |
used swap memory percentage against total swap space |
#{swap.total} |
total swap space |
free/used/total memory can be shown both in absolute and relative units. When it comes to absolute units, you can choose size scale factor to choose between GiB, MiB, KiB. Default is GiB. If you have less than 3-4G memory installed, it makes sense to use MiB. KiB option is less practical, because it yields pretty lengthy output, which does not fit status bar limited estate.
set -g @sysstat_mem_size_unit "G"
If you choose G for size scale, output will have %.1f (1 digit after floating point), otherwise size is integer (4.5G, 1024M, 1232345K).
Each metric output is colored by default. Colors vary depending on metric value.
| Threshold | CPU | Memory | Swap | Default color |
| low | x < 30% | x < 75% | x < 25% | green |
| medium | 30% < x < 80% | 75% < x < 90% | 25% < x < 75% | yellow |
| high | x > 80% | x > 90% | x > 75% | red |
You can change thresholds in your .tmux.conf:
set -g @sysstat_cpu_medium_threshold "75"
set -g @sysstat_cpu_stress_threshold "95"
set -g @sysstat_mem_medium_threshold "85"
set -g @sysstat_mem_stress_threshold "95"
set -g @sysstat_swap_medium_threshold "80"
set -g @sysstat_swap_stress_threshold "90"
You can change colors for each threshold individually. You can use ANSI basic colors (red, cyan, green) or if your terminal supports 256 colors (and most do nowadays), use colourXXX format.
set -g @sysstat_cpu_color_low "colour076"
set -g @sysstat_cpu_color_medium "colour220"
set -g @sysstat_cpu_color_stress "colour160"
set -g @sysstat_mem_color_low "green"
set -g @sysstat_mem_color_medium "blue"
set -g @sysstat_mem_color_stress "cyan"
#{(mem|cpu|swap).color} placeholder in your @sysstat_(mem|cpu|swap)_view_tmpl would be replaced by corresponding color, depending on whether metric value falls in particular threshold.
For 256 color palette support, make sure that tmux and parent terminal are configured with correct terminal type. See here and there
# ~/.tmux.conf
set -g default-terminal "screen-256color"
# parent terminal
$ echo $TERM
xterm-256color
# jump into a tmux session
$ tmux new
$ echo $TERM
screen-256color
You can have up to 3 colors configured for each threshold. To understand why you might need this, let tackle this task. Note, this is rather advanced use case.
I want
CPU: #{cpu.pused}metric output, have green and yellow text colors at "low" and "medium" threshold, and finally, for "high" threshold, I want to use red color, but reverse foreground and background, that is use red for background, and white for text. More over I want "CPU:" text colored apart in red
Like this:
You can achieve the result using following configuration:
set -g @sysstat_cpu_view_tmpl '#[fg=#{cpu.color3}]CPU:#[default] #[fg=#{cpu.color},bg=#{cpu.color2}]#{cpu.pused}#[default]'
set -g @sysstat_cpu_color_low "$color_level_ok default default"
set -g @sysstat_cpu_color_medium "$color_level_warn default default"
set -g @sysstat_cpu_color_stress "white,bold $color_level_stress $color_level_stress"
You can configure status refresh interval, increasing or reducing frequency of tmux-plugin-sysstat command invocations.
set -g status-interval 5
It's adviced to set status-interval to some reasonable value, like 5-10 seconds. More frequent updates (1 second) are useless, because they distract, and results in extra resource stress spent on metrics calculation itself.
NOTE: Stop here if you want to just use this plugin without making your feet wet. If you're hardcore tmux user and are curious about internals, keep reading
Internally, we use iostat and top on OSX, and vmstat and top on Linux to collect metric value. Neither requires you to install extra packages. These commands are run in sampling mode to report stats every N seconds M times. First sample include average values since the system start. Second one is the average CPU per second for last N seconds (exactly what we need)
For example:
$ iostat -c 2 -w 5
disk0 cpu load average
KB/t tps MB/s us sy id 1m 5m 15m
44.22 6 0.26 3 2 95 1.74 1.90 2.15
5.47 8 0.04 4 5 91 1.84 1.92 2.16 << use this row, 2nd sample
We align CPU calculation intervals (-w) with tmux status bar refresh interval (status-interval setting).
You might ask what we treat as free memory and how it's calculated.
Let's start with OSX. We use vm_stat command (not same as vmstat on Linux), which reports following data (number of memory pages, not KB):
$ vm_stat
Pages free: 37279
Pages active: 1514200
Pages inactive: 1152997
Pages speculative: 6214
Pages throttled: 0
Pages wired down: 1174408
Pages purgeable: 15405
Pages stored in compressor: 1615663
Pages occupied by compressor: 306717
Total installed memory formula is:
Total = free + active + inactive + speculative + occupied by compressor + wired
where
free, completely unused memory by the systemwired, critical information stored in RAM by system, kernel and key applications. Never swapped to the hard drive, never replaced with user-level data.active, information currently in use or very recently used by applications. When this kind of memory is not used for long (or application is closed), it's move to inactive memory.inactive, like buffers/cached memory in Linux. Memory for applications, which recently exited, retained for faster start-up of same application in future.
So the question what constitutes free and used memory. It turns out, that various monitoring and system statistics tools on OSX each calculate it differently.
- htop:
used = active + wired,free=total - used - top. Used =
used = active + inactive + occupied by compressor + wired; Free =free + speculativeResident set size (RSS) =active - OSX activity Monitor. Used =
app memory + wired + compressor. Note, it's not clear what is app memory.
In general, they either treat currently used memory, which can be reclaimed in case of need (cached, inactive, occupied by compressor), as used or free.
It makes sense to talk about available memory rather than free one. Available memory is unused memory + any used memory which can be reclaimed for application needs.
So, tmux-plugin-sysstat, uses following formula:
used = active + wired
available/free = free/unused + inactive + speculative + occupied by compressor
Same thinking can be applied to Linux systems.
Usually commands like free report free/unused, used, buffers, cache memory kinds.
$ free
total used free shared buffers cached
Mem: 1016464 900236 116228 21048 93448 241544
-/+ buffers/cache: 565244 451220
Swap: 1046524 141712 904812
Second line indicates available memory (free + buffers + cache), with an assumption that buffers and cache can be 100% reclaimed in case of need.
However, we're not using free, because its output varies per system. For example on RHEL7, there is no -/+ buffers/cache, and available memory is reported in different way. We read directly from /proc/meminfo
$ cat /proc/meminfo
MemTotal: 1016232 kB
MemFree: 152672 kB
MemAvailable: 637832 kB
Buffers: 0 kB
Cached: 529040 kB
tmux-plugin-sysstat uses following formula:
free/available = MemAvailable; // if MemAvailable present
free/available = MemFree + Buffers + Cached;
used = MemTotal - free/avaialble
Using MemAvailable is more accurate way of getting available memory, rather than manual calculation free + buffers + cache, because the assumption that buffers + cache can be 100% reclaimed for new application needs might be wrong. When using MemAvailable, OS calculates available memory for you, which is apparently better and accurate approach.
See this topic on more reasoning about MemAvailable field.
