cpustat(1M)															       cpustat(1M)

NAME

       cpustat - monitor system behavior using CPU performance counters

SYNOPSIS

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

       If  interval  is specified, cpustat samples activity every interval seconds, 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 monitor. The syntax of these event specifications 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 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.

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

		       When this option is present, the optional count parameter specifies the number of total cycles to make (instead of the num-
		       ber  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  trigger-
		       ing system-mode events.

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

       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 attributes:

       +-----------------------------+-----------------------------+
       |      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),  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
       cpc_bind_cpu(3CPC).

								    18 Jul 2005 						       cpustat(1M)