cpustat man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

CPUSTAT(1M)							   CPUSTAT(1M)

       cpustat - monitor system behavior using CPU performance counters

       cpustat -c eventspec [-c eventspec]... [-p period] [-T u | d ]
	    [-sntD] [interval [count]]

       cpustat -h

       The cpustat utility allows CPU performance counters to be used to moni‐
       tor the overall behavior of the CPUs in the system.

       If interval is specified, cpustat samples activity every interval  sec‐
       onds,  repeating	 forever.  If a count is specified, 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 performance counters to moni‐
	   tor.	 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 hexadecimal, octal, or decimal
	   notation,  in  a  format  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.


	   Enables debug mode.


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


	   Omits  all  header  output (useful if cpustat is the beginning of a

       -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 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 interval, the tool acts as it period is 0.


	   Creates  an idle soaker thread to spin while system-only eventspecs
	   are bound. One idle soaker thread is bound to each CPU in the  cur‐
	   rent	 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

	   Display a time stamp.

	   Specify u for a printed representation of the internal  representa‐
	   tion	 of time. See time(2). Specify d for standard date format. See


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

       A  closely  related  utility,  cputrack(1),  can be used to monitor 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 performance counters sys‐
       tem-wide by cpustat and the use of the CPU performance counters to mon‐
       itor 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 pro‐
       gram 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 settings 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 implementation restrictions, overflows can be  lost
       unless  the  sampling  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 samples.

       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 accessible to it in
       the  current  processor set. Thus, several instances of the utility can
       be running on the CPUs in different 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

       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 Pentium 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 invo‐
       cations 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

       See attributes(5) for descriptions of the following attributes:

       │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),	 geth‐
       rtime(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

				 Jun 16, 2009			   CPUSTAT(1M)

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net