cpustat

 

---

 
 
 
 Maintenance Commands                                  cpustat(1M)
 
 
 


NAME
      cpustat - monitor  system  behavior  using  CPU  performance
      counters
 


SYNOPSIS
      cpustat -c eventspec   [ -c eventspec ]  ...  [  -ntD  ]   [
      interval  [ count ]  ]
 
      cpustat -h
 


DESCRIPTION
      The cpustat utility allows CPU performance  counters  to  be
      used to monitor the overall behavior of the CPUs in the sys-
      tem.
 
      If interval is specified,  cpustat  samples  activity  every
      interval  seconds,  repeating forever.  If a count is speci-
      fied, the statistics are repeated count  times.  If  neither
      are  specified,  an  interval  of  five seconds is used, and
      there is no limit to the number  of  samples  that  will  be
      taken.
 


OPTIONS
      The following options are supported:
 
      -c eventspec
            Specify a  set  of  events  for  the  CPU  performance
            counters to monitor. The syntax of these event specif-
            ication can be determined using the -h option to cause
            the  usage  message  to be generated. The semantics of
            these event specifications can be determined by  read-
            ing   the  CPU  manufacturers  documentation  for  the
            events. See cpc_strtoevent(3CPC) for a description  of
            the syntax.
 
            Multiple -c options may be specified,  in  which  case
            the  command  cycles  between the different event set-
            tings on each sample.
 
      -D    Enable debug mode.
 
      -h    Print an extensive help message  on  how  to  use  the
            utility  and  how  to  program the processor-dependent
            counters.
 
      -n    Omit all header  output  (useful  if  cpustat  is  the
            beginning of a pipeline).
 
      -t    Print an additional column of processor cycle  counts,
            if available on the current architecture.
 
 
 
 
 
 SunOS 5.8           Last change: 14 Sep 1999                    1
 
 
 
 
 
 
 Maintenance Commands                                  cpustat(1M)
 
 
 
 USAGE
      A closely related utility, cputrack(1), can be used to moni-
      tor  the  behavior of individual applications with little or
      no interference from other activities on the system.
 
      The cpustat utility must be run by the super-user, as  there
      is  an intrinsic conflict between the use of the CPU perfor-
      mance counters system-wide by cpustat and the use of the CPU
      performance  counters  to monitor an individual process (for
      example, by cputrack.)
 
      Once any instance of this utility has  started,  no  further
      per-process  or per-LWP use of the counters is allowed until
      the last instance of the utility terminates.
 
      The times printed by the command correspond to the wallclock
      time  when  the  hardware  counters  were  actually sampled,
      instead of when the program told the kernel to sample  them.
      The time is derived from the same timebase as gethrtime(3C).
 
      The processor cycle counts enabled by the -t  option  always
      apply  to both user and system modes, regardless of the set-
      tings applied to the performance counter registers.
 
      The output of cpustat is designed to be readily parseable by
      nawk(1)  and  perl(1), thereby allowing performance tools to
      be composed by embedding cpustat in scripts.  Alternatively,
      tools  may  be constructed directly using the same APIs that
      cpustat is built upon using the facilities of  libcpc(3LIB).
      See cpc(3CPC).
 
      The cpustat utility only monitors the CPUs that are accessi-
      ble  to  it  in  the  current  processor  set.  Thus several
      instances of the  utility can be running on the CPUs in dif-
      ferent  processor  sets. See psrset(1M) for more information
      about processor sets.
 
      Because cpustat uses LWPs bound to  CPUs,  the  utility  may
      have  to terminated before the configuration of the relevant
      processor can be changed.
 
 WARNING
      By running the cpustat command, the superuser will  forcibly
      invalidate  all existing performance counter context.   This
      may in turn cause all invocations of the  cputrack  command,
      and  other  users  of  performance  counter context, to exit
      prematurely with unspecified errors.
 


ATTRIBUTES
      See attributes(5) for descriptions of the  following  attri-
      butes:
 
 
 
 
 SunOS 5.8           Last change: 14 Sep 1999                    2
 
 
 
 
 
 
 Maintenance Commands                                  cpustat(1M)
 
 
 
      ____________________________________________________________
     |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
     | Availability                | SUNWcpcu                    |
     | Interface Stability         | Evolving                    |
     |_____________________________|_____________________________|
 
 


SEE ALSO
      cputrack(1),  nawk(1),  perl(1),   iostat(1M),   prstat(1M),
      psrset(1M),   vmstat(1M),  cpc(3CPC),  cpc_strtoevent(3CPC),
      gethrtime(3C), libcpc(3LIB), attributes(5)
 
      Sun Microelectronics UltraSPARC I&II User's Manual,  January
      1997, STP1031, http://www.sun.com/sparc"
 
      Intel Architecture Software Developer's  Manual,  Volume  3:
      System Programmers Guide, 243192, http://developer.intel.com
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 SunOS 5.8           Last change: 14 Sep 1999                    3
 
 
 

---