NAME

       cpustat - a tool to measure CPU utilization.

SYNOPSIS

       cpustat [ options ] [delay [count]]

DESCRIPTION

       cpustat  is  a  program  that dumps the CPU utilization of current running tasks (that is,
       processes or kernel threads).  cpustat is useful to monitor the  activity  of  long  lived
       processes in a system, such as daemons, kernel threads as well as typical user processes.

       cpustat  shows  only the tasks that have measured any change in their CPU activity between
       each sample interval (as indicated by an increment in the CPU tick count  stats  of  utime
       and  stime in /proc/$pid/stat).  cpustat thus only reports activity of busy tasks that are
       still alive at the time of each sample snapshot and hence will not account for very  short
       lived processes that exist between each sample period.

       For  each  running  task  that has consumed some CPU during the sample time, the following
       information is displayed:

                    Heading      Description
                    %CPU         Total CPU used (in percent)
                    %USR         CPU used in user space (in percent)
                    %SYS         CPU used in system (kernel) space (in percent)
                    PID          Process ID
                    S            Process  State,  R  (Running),  S  (Sleeping),   D
                                 (Waiting,  Disk  Sleep),  T  (Stopped), t (Tracing
                                 stopped),  W  (Paging),  X  (Dead),  x  (Dead),  K
                                 (Wakekill), W (Waking), P (Parked).
                    CPU          CPU used by the process at time of sampling.
                    Time         Total  CPU  time  used  by  the  process  since it
                                 started.
                    Task         Process command  line  information  (from  process
                                 cmdline or comm fields)

       cpustat  was designed to try and minimize the CPU overhead of process statistics gathering
       and reporting. It is therefore ideal for small embedded devices where CPU is limited where
       measuring  CPU  utilisation  may affect the overall CPU statistics. For this reason, it is
       not as complex as tools such as top(1) that have a more feature rich user interface.

OPTIONS

       cpustat options are as follow:

       -a     calculate CPU utilisation based on all CPUs. For example, if  a  process  is  using
              100%  of  1  CPU  and the system has 4 CPUs, then the utilisation will show as 25%.
              The default is to show utilisation on a per CPU basis.

       -c     get command information from process comm field.

       -d     strip directory basename off command information.

       -D     compute and show the distribution of CPU utilisation by task and by CPU.
              By task, this breaks the CPU utilisation of each task into 20 ranges  from  minimum
              to  the maximum and shows the count of tasks found at in that paricular utilisation
              range.  Useful to see any outliers and to characterize the typical per  task  usage
              of the CPU.
              By CPU, this shows the user and system CPU utilisation by per CPU.

       -g     show  grand  total of CPU utilisation statistics at the end of the run. This is the
              total cumulatave CPU used by each process, averaged over the entire run duration.

       -h     show help.

       -i     ignore cpustat in the statistics.

       -l     show long (full) command information.

       -n task_count
              only display the first task_count number of top tasks.

       -p PID onlt display process that matches the given PID.

       -q     run quietly, only really makes sense with -r option.

       -r csv_file
              output gathered data in a comma separated values file. This can  be  then  imported
              and  graphed  using  your  favourite open source spread sheet. The %CPU utilisation
              (system and user) for each process at each sample time is output into a table.

       -s     show short command information.

       -S     show time stamp. If the -r option is used then an extra column appears in  the  CSV
              output file with the time of day for each sample.

       -t threshold
              ignore samples where the CPU usage delta per second less than the given threshold.

       -T     calculate total CPU utilisation.

       -x     show  extra  CPU  related  statistics,  namely:  CPU  load average over 1, 5 and 10
              minutes, CPU frequency (average of all online  CPU  frequencies),  number  of  CPUs
              online.

EXAMPLES

       cpustat

              Dump CPU stats every second until stopped.

       cpustat -n 20 60

              Dump the top 20 CPU consuming tasks every 60 seconds until stopped.

       cpustat 10 5

              Dump CPU stats every 10 seconds just 5 times.

       cpustat -x -D -a 1 300

              Gather  stats  every  second  for  5  minutes  with  extra  CPU  stats and show CPU
              utilisation distributions per task and per CPU at the end of the run.  Also,  scale
              CPU  utilisation  by  the number of CPUs so that 100% utilisation means 100% of all
              CPUs rather than 100% of 1 CPU.

SEE ALSO

       forkstat(8), eventstat(8), vmstat(8), top(1)

AUTHOR

       cpustat was written by Colin King <colin.king@canonical.com>

       This manual page was written by Colin  King  <colin.king@canonical.com>,  for  the  Ubuntu
       project (but may be used by others).

COPYRIGHT

       Copyright © 2011-2015 Canonical Ltd.
       This  is  free software; see the source for copying conditions.  There is NO warranty; not
       even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

                                         August 14, 2015                               CPUSTAT(8)