Sun Microsystems, Inc.
spacerspacer
spacer   www.sun.com docs.sun.com | | |  
spacer
black dot
   
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
    
 
System Administration Commandscpustat(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 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 will be 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 specification 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 reading 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 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.
-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.

USAGE

 

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 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 settings applied to the performance counter registers.

On some hardware platforms, 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 may 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 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 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 may have to be terminated before the configuration of the relevant processor can be changed.

WARNINGS

 

By running the cpustat command, the super-user 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.

If cpustat is invoked on a system that has CPU performance counters, but on which the packages containing the kernel support for those counters is not installed, the following message appears:

 
cpustat: CPU performance counters are inaccessible on this machine

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

ATTRIBUTES

 

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

ATTRIBUTE TYPEATTRIBUTE VALUE
AvailabilitySUNWcpcu
Interface StabilityEvolving

SEE ALSO

 

cputrack(1), nawk(1), perl(1), iostat(1M), prstat(1M), psrset(1M), vmstat(1M), cpc(3CPC), cpc_access(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.9Go To TopLast Changed 27 Sep 25 Jun 2001

 
      
      
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.