Reformatting page.  Please Wait... done


Maintenance Commands                                  CPUSTAT(1M)


NAME
     cpustat - monitor  system  behavior  using  CPU  performance
     counters

SYNOPSIS
     cpustat -c eventspec [-c eventspec]... [-p period] [-T u | d ]
          [-sntD] [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 are taken.

OPTIONS
     The following options are supported:

     -c eventspec

         Specifies a  set  of  events  for  the  CPU  performance
         counters to monitor.  The syntax of these event specifi-
         cations is:

           [picn=]eventn[,attr[n][=val]][,[picn=]eventn
                [,attr[n][=val]],...,]


         You can use the -h option to obtain a list of  available
         events  and  attributes.  This  causes generation of the
         usage message. You can omit an explicit counter  assign-
         ment, in which case cpustat attempts to choose a capable
         counter automatically.

         Attribute values can be expressed in hexadecimal, octal,
         or   decimal   notation,   in   a  format  suitable  for
         strtoll(3C). An attribute present in the event  specifi-
         cation  without  an  explicit  value  receives a default
         value of 1. An attribute without a corresponding counter
         number is applied to all counters in the specification.

         The semantics  of  these  event  specifications  can  be
         determined    by    reading   the   CPU   manufacturer's


Illumos             Last change: Jun 16, 2009                   1


Maintenance Commands                                  CPUSTAT(1M)


         documentation for the events.

         Multiple -c options can be specified, in which case  the
         command  cycles  between the different event settings on
         each sample.


     -D

         Enables debug mode.


     -h

         Prints an extensive help message on how to use the util-
         ity and how to program the processor-dependent counters.


     -n

         Omits all header output (useful if cpustat is the begin-
         ning of a pipeline).


     -p period

         Causes cpustat to cycle through the list  of  eventspecs
         every  period  seconds. The tool sleeps after each cycle
         until  period  seconds  have  elapsed  since  the  first
         eventspec was measured.

         When this option is present, the optional count  parame-
         ter  specifies  the  number  of  total  cycles  to  make
         (instead of the number of total  samples  to  take).  If
         period  is  less  than  the  number  of eventspecs times
         interval, the tool acts as it period is 0.


     -s

         Creates an idle soaker thread to spin while  system-only
         eventspecs are bound. One idle soaker thread is bound to
         each CPU  in  the  current  processor  set.  System-only
         eventspecs  contain  both  the nouser and the sys tokens
         and measure events that occur while the CPU is operating
         in  privileged  mode.  This option prevents the kernel's
         idle  loop  from  running  and  triggering   system-mode
         events.


     -T u | d


Illumos             Last change: Jun 16, 2009                   2


Maintenance Commands                                  CPUSTAT(1M)


         Display a time stamp.

         Specify u for a printed representation of  the  internal
         representation of time. See time(2). Specify d for stan-
         dard date format. See date(1).


     -t

         Prints an additional column of processor  cycle  counts,
         if available on the current architecture.


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.


     On some hardware platforms running in system mode using  the
     "sys"  token,  the  counters  are  implemented  using 32-bit
     registers. While the kernel attempts to catch all  overflows
     to synthesize 64-bit counters, because of hardware implemen-
     tation restrictions, overflows can be lost unless  the  sam-
     pling  interval  is kept short enough. The events most prone
     to wrap are those that count processor clock cycles. If such
     an event is of interest, sampling should occur frequently so
     that less than 4 billion clock cycles can occur between sam-
     ples.


Illumos             Last change: Jun 16, 2009                   3


Maintenance Commands                                  CPUSTAT(1M)


     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  can  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  might
     have  to  be  terminated  before  the  configuration  of the
     relevant processor can be changed.

EXAMPLES
  SPARC
     Example 1 Measuring External Cache References and Misses


     The following example measures misses and references in  the
     external  cache.  These occur while the processor is operat-
     ing in user mode on an UltraSPARC machine.


       example% cpustat -c EC_ref,EC_misses 1 3

           time cpu event      pic0      pic1
          1.008   0  tick     69284      1647
          1.008   1  tick     43284      1175
          2.008   0  tick    179576      1834
          2.008   1  tick    202022     12046
          3.008   0  tick     93262       384
          3.008   1  tick     63649      1118
          3.008   2 total    651077     18204


  x86
     Example 2 Measuring Branch Prediction Success on Pentium 4


     The following example  measures  branch  mispredictions  and
     total  branch instructions in user and system mode on a Pen-
     tium 4 machine.


        example% cpustat -c \


Illumos             Last change: Jun 16, 2009                   4


Maintenance Commands                                  CPUSTAT(1M)


           pic12=branch_retired,emask12=0x4,pic14=branch_retired,\
           emask14=0xf,sys 1 3

           time cpu event      pic12     pic14
          1.010   1  tick       458       684
          1.010   0  tick       305       511
          2.010   0  tick       181       269
          2.010   1  tick       469       684
          3.010   0  tick       182       269
          3.010   1  tick       468       684
          3.010   2 total      2063      3101


     Example 3 Counting Memory Accesses on Opteron


     The  following  example  determines  the  number  of  memory
     accesses  made through each memory controller on an Opteron,
     broken down by internal memory latency:


       cpustat -c \
          pic0=NB_mem_ctrlr_page_access,umask0=0x01, \
          pic1=NB_mem_ctrlr_page_access,umask1=0x02, \
          pic2=NB_mem_ctrlr_page_access,umask2=0x04,sys \
          1

           time cpu event      pic0      pic1      pic2
          1.003   0  tick     41976     53519      7720
          1.003   1  tick      5589     19402       731
          2.003   1  tick      6011     17005       658
          2.003   0  tick     43944     45473      7338
          3.003   1  tick      7105     20177       762
          3.003   0  tick     47045     48025      7119
          4.003   0  tick     43224     46296      6694
          4.003   1  tick      5366     19114       652


WARNINGS
     By running the  cpustat  command,  the  super-user  forcibly
     invalidates  all  existing performance counter context. This
     can in turn cause all invocations of the  cputrack  command,
     and  other  users  of  performance  counter context, to exit
     prematurely with unspecified errors.


     If cpustat is invoked on a system that has  CPU  performance
     counters  which  are not supported by Solaris, the following
     message appears:


Illumos             Last change: Jun 16, 2009                   5


Maintenance Commands                                  CPUSTAT(1M)


       cpustat: cannot access performance counters - Operation not applicable


     This error message implies that cpc_open() has failed and is
     documented  in cpc_open(3CPC). Review this documentation for
     more information about the problem and possible solutions.


     If a short interval is requested, cpustat might not be  able
     to  keep up with the desired sample rate. In this case, some
     samples might be dropped.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:


     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|_________________|
    | Interface Stability|  Evolving       |
    |____________________|_________________|


SEE ALSO
     cputrack(1),  nawk(1),  perl(1),   iostat(1M),   prstat(1M),
     psrset(1M),     vmstat(1M),    cpc(3CPC),    cpc_open(3CPC),
     cpc_bind_cpu(3CPC),       gethrtime(3C),        strtoll(3C),
     libcpc(3LIB)attributes(5)

NOTES
     When cpustat is run  on  a  Pentium  4  with  HyperThreading
     enabled,  a CPC set is bound to only one logical CPU of each
     physical CPU. See cpc_bind_cpu(3CPC).


Illumos             Last change: Jun 16, 2009                   6