Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1m‎ > ‎


     cpustat - monitor  system  behavior  using  CPU  performance

     cpustat -c eventspec  [-c eventspec]... [-p period]  [-sntD]
     [ interval [count]]

     cpustat -h

     The cpustat utility allows CPU performance  counters  to  be
     used to monitor the overall behavior of the CPUs in the sys-

     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.

     The following options are supported:

     -c eventspec    Specifies a set of events for the  CPU  per-
                     formance  counters to monitor. The syntax of
                     these event specifications is:


                     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 assignment, in
                     which case  cpustat  attempts  to  choose  a
                     capable counter automatically.

                     Attribute values can be expressed in hexade-
                     cimal, octal, or decimal notation, in a for-
                     mat suitable for strtoll(3C).  An  attribute
                     present  in  the event specification 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 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  utility  and  how  to  program the
                     processor-dependent counters.

     -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

                     When this option is  present,  the  optional
                     count  parameter  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  inter-
                     val, 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

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

     -t              Prints an  additional  column  of  processor
                     cycle  counts,  if  available on the current

     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-

     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.

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

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

         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

     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:

     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.

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

    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | Availability                | SUNWcpcu                    |
    | Interface Stability         | Evolving                    |

     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)

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

Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.