powerstat.8

.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH POWERSTAT 8 "12 January 2024"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
powerstat \- a tool to measure power consumption
.br

.SH SYNOPSIS
.B powerstat
[options]
.RI [ delay " [" count ]]
.br

.SH DESCRIPTION
powerstat measures the power consumption of a computer
that has a battery power source or supports the RAPL (Running Average Power
Limit) interface.  The output is like vmstat but also shows power
consumption statistics.  At the end of a run, powerstat will calculate
the average, standard deviation, minimum, maximum and geometic mean of
the gathered data.
.br

Note that running powerstat as root will provide extra information about
process fork(2), exec(2) and exit(2) activity.

.SH OPTIONS
powerstat options are as follow:
.TP
.B \-a
enable all statistics gathering options, equivalent to \-c, \-f, \-g, \-t and \-H.
.TP
.B \-b
redo a sample measurement if a system is busy, the default for busy is considered less than 98% CPU idle. The CPU idle threshold can be altered using the \-i option.
.TP
.B \-c
gather CPU C-state activity and show the % time and count in each C-state at the end of the run. 
.TP
.B \-d delay
specify delay in seconds before starting, default is 180 seconds when running on battery or 0 seconds when using RAPL. This gives the machine time to settle down and for the battery readings to stabilize.
.TP
.B \-D
enable extra power stats showing all the power domain power readings. This currently only applies to the \-R RAPL option.
.TP
.B \-f
compute the geometric mean of all on-line CPU core frequencies. Unfortunately a CPU core is always active to gather any form of stats because
powerstat has to be running to do so, so these statistics are skewed by this.  It is best to use this option with a reasonably large delay
(more than 5 seconds) between samples to reduce the overhead of powerstat.
.TP
.B \-g
report GPU frequency of card0.
.TP
.B \-h
show help.
.TP
.B \-H
show histogram of power measurements.
.TP
.B \-i threshold
specify the idle threshold (in % CPU idle) to force a re-sample measurement if the CPU is less idle than this level. This option implicitly enables the \-b option.
.TP
.B \-n
no headings. Column headings are printed when they scroll off the terminal; this option disables this and allows one to capture the output and parse the data
without the need to filter out the headings.
.TP
.B \-p
redo a sample measurement if any processes fork(), exec() or exit().
.TP
.B \-r
redo if system is not idle and any processes fork(), exec() or exit(), an alias for \-p \-b.
.TP
.B \-R
read power statistics from the RAPL (Running Average Power Limit) domains. This is supported
by recent Linux kernels and Sandybridge and later Intel processors.  This only covers some
of the hardware in the machine, such as the processor package, DRAM controller, CPU core
(power plane 0), graphics uncore (power plane 1) and so forth, so the readings do not cover
the entire machine.
.br
Because the  RAPL readings are accurate and available immediately, the start delay (\-d option)
is defaulted to zero seconds.
.TP
.B \-s
this dumps a log of the process fork(), exec() and exit() activity on completion.
.TP
.B \-S
use standard averaging to calculate power consumption instead of using
a 120 second rolling average of capacity samples. This is only useful
if the battery reports just capacity values and is an alternative method
of calculating the power consumption based on the start and current battery
capacity.
.TP
.B \-t
gather temperatures from all the available thermal zones on the device. If there
are no thermal zones available then nothing will be displayed.
.TP
.B \-z
forcibly ignore zero power rate readings from the battery. Use this to gather other statistics
(for example when using \-c, \-f, \-t options) if powerstat cannot measure power (not discharging
or no RAPL interface).
.SH EXAMPLES
.LP
Measure power with the default of 10 samples with an interval of 10 seconds
.RS 8
powerstat
.RE
.LP
Measure power with 60 samples with an interval of 1 second
.RS 8
powerstat 1 60
.RE
.LP
Measure power and redo sampling if we are not idle and we detect  fork()/exec()/exit() activity
.RS 8
sudo powerstat \-r
.RE
.LP
Measure power using the Intel RAPL interface:
.RS 8
powerstat \-R
.RE
.LP
Measure power using the Intel RAPL interface and show extra RAPL domain power readings and power
measurement histogram at end of the run
.RS 8
powerstat \-RDH
.RE
.LP
Measure power and redo sampling if less that 95% idle
.RS 8
powerstat \-i 95
.RE
.LP
Wait to settle for 1 minute then measure power every 20 seconds and show any fork()/exec()/exit() activity at end of the measuring
.RS 8
powerstat \-d 60 \-s 20
.RE
.LP
Measure temperature, CPU frequencies, C-states, power via RAPL domains, produce histograms, don't print repeated headings and measure every 0.5 seconds
.RS 8
powerstat -tfcRHn 0.5
.RE
.SH SEE ALSO
.BR vmstat (8), 
.BR powertop (8),
.BR power-calibrate (8)
.SH AUTHOR
powerstat was written by Colin Ian King <colin.i.king@gmail.com>
.PP
This manual page was written by Colin Ian King <colin.i.king@gmail.com>,
for the Ubuntu project (but may be used by others).
.SH COPYRIGHT
Copyright \(co 2011-2021 Canonical Ltd. Copyright \(co 2021-2025 Colin Ian King
.br
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.