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
       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.

PROCESS STATE CODES

       R        Running
       S        Sleeping
       D        Waiting, Disk Sleep
       T        Stopped
       t        Tracing stopped
       W        Paging
       X or x   Dead
       K        Wakekill
       W        Waking
       P        Parked

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 particular 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 only 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.

       -X     run in curses based "top" like mode; this will make cpustat consume more CPU cycles as it adds  on
              more display handling overhead.

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 Ian King <colin.i.king@gmail.com>

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

COPYRIGHT

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

                                                 January 8, 2024                                      CPUSTAT(8)