- online man pages   

SunOS man pages : cputrack (1)

User Commands                                         cputrack(1)


cputrack - monitor process and LWP behavior using CPU per- formance counters


cputrack -c eventspec [ -c eventspec ] ... [ -efntvD ] [ -N count ] [ -o pathname ] [ -T interval ] command [ args ] cputrack -c eventspec [ -c eventspec ] ... -p pid [ -efntvD ] [ -N count ] [ -o pathname ] [ -T interval ] cputrack -h


The cputrack utility allows CPU performance counters to be used to monitor the behavior of a process or family of processes running on the system. If interval is specified with the -T option, cputrack samples activity every interval seconds, repeating forever. If a count is specified with the -N option, the statistics are repeated count times for each process tracked. If neither are specified, an interval of one second is used. If command and optional args are specified, cputrack runs the command with the arguments given while monitoring the specified CPU performance events. Alternatively, the process ID of an existing process can be specified using the -p option. Because cputrack is an unprivileged program, it is subject to the same restrictions that apply to truss(1). For exam- ple, setuid(2) executables cannot be tracked.


The following options are supported: -c eventspec Specify a set of events for the CPU performance counters to monitor. The list of available events and the syntax of the event specifications for the system can be determined using the -h option. 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 cputrack cycles between the different event settings on each sample. -D Enable debug mode. -e Follow all exec(2), or execve(2) system calls. SunOS 5.8 Last change: 14 Sep 1999 1 User Commands cputrack(1) Without this option, cputrack terminates when the pro- cess image is overlaid with a new executable. -f Follow all children created by fork(2), fork1(2), or vfork(2) system calls. -h Print an extended help message on how to use the util- ity and how to program the processor-dependent counters. -n Omit all header output (useful if cputrack is the beginning of a pipeline). -N count Specify the maximum number of CPU performance counter samples to take before exiting. -o outfile File to be used for the cputrack output. -p pid Interpret the argument as the process ID of an exist- ing process to which process counter context should be attached and monitored. -t Print an additional column of processor cycle counts, if available on the current architecture. -T interval Specify the interval between CPU performance counter samples in seconds. -v Enable more verbose output.


The operating system enforces certain restrictions on the tracing of processes. In particular, a command whose object file cannot be read by a user cannot be tracked by that user; set-uid and set-gid commands can only be tracked by a privileged user. Unless it is run by a privileged user, cpu- track loses control of any process that performs an exec() of a set-id or unreadable object file; such processes con- tinue normally, though independently of cputrack, from the point of the exec(). The system may run out of per-user process slots when the -f option is used, since cputrack runs one controlling process for each process being tracked. The times printed by cputrack correspond to the wallclock time when the hardware counters were actually sampled, instead of when the program told the kernel to sample them. SunOS 5.8 Last change: 14 Sep 1999 2 User Commands cputrack(1) The time is derived from the same timebase as gethrtime(3C). The cputrack utility attaches performance counter context to each process that it examines. The presence of this context allows the performance counters to be multiplexed between different processes on the system, but it cannot be used at the same time as the cpustat(1M) utility. Once an instance of the cpustat utility is running, further attempts to run cputrack will fail until all instances of cpustat terminate. Sometimes cputrack provides sufficient flexibility and prints sufficient statistics to make adding the event selec- tion code to an application unnecessary. However, more con- trol is occasionally desired. Because the same performance counter context is used by both the application itself and by the agent LWP injected into the application by cputrack, it is possible for an application to interact with the counter context to achieve some interesting capabilities. See cpc_count_usr_events(3CPC). 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. The output of cputrack is designed to be readily parseable by nawk(1) and perl(1), thereby allowing performance tools to be composed by embedding cputrack in scripts. Alterna- tively, tools may be constructed directly using the same APIs that cputrack is built upon using the facilities of libcpc(3LIB) and libpctx(3LIB). See cpc(3CPC). Although cputrack uses performance counter context to main- tain separate performance counter values for each LWP, some of the events that can be counted will inevitably be impacted by other activities occurring on the system; par- ticularly for limited resources that are shared between processes (for example, cache miss rates.) For such events, it may also be interesting to observe overall system behavior with cpustat(1M).


SPARC Example 1: SPARC example of cputrack In this example, the utility is being used on a machine con- taining an UltraSPARC 1 processor. The counters are set to count processor clock cycles and instructions dispatched in user mode while running the sleep(1) command. SunOS 5.8 Last change: 14 Sep 1999 3 User Commands cputrack(1) % cputrack -c pic0=Cycle_cnt,pic1=Instr_cnt sleep 10 time lwp event pic0 pic1 2.040 1 tick 377820 202593 4.028 1 tick 0 0 6.028 1 tick 0 0 8.028 1 tick 0 0 10.028 1 tick 6930 954 10.036 1 exit 410623 212137 Example 2: SPARC example of cputrack This example shows more verbose output while following the fork() and exec() of a simple shell script on an UltraSPARC machine. The counters are measuring the number of external cache references and external cache hits. Note that the explicit pic0 and pic1 names can be omitted where there are no ambiguities. % cputrack -fev -c EC_ref,EC_hit /bin/ulimit -c time pid lwp event pic0 pic1 0.032 101200 1 init_lwp 0 0 0.106 101200 1 fork # 101201 0.115 101201 1 init_lwp 0 0 0.179 101201 1 fini_lwp 5934 5031 0.179 101201 1 exec 5934 5031 0.399 101201 1 exec # 'basename /bin/ulimit' 0.413 101201 1 init_lwp 0 0 0.435 101201 1 fini_lwp 19780 17234 0.435 101201 1 exit 19780 17234 unlimited 0.454 101200 1 fini_lwp 63025 54583 0.454 101200 1 exit 63025 54583 IA Example 3: IA example of cputrack This example shows how many instructions were executed in the application and in the kernel to print the date on a Pentium machine: % cputrack -c inst_retired,inst_retired,nouser1,sys1 date time lwp event pic0 pic1 Fri Aug 20 20:03:08 PDT 1999 0.072 1 exit 246725 339666


By running any instance of the cpustat(1M) utility, all existing performance counter context is forcibly invalidated across the machine. This may in turn cause all invocations of the cputrack command to exit prematurely with unspecified errors. SunOS 5.8 Last change: 14 Sep 1999 4 User Commands cputrack(1)


See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWcpcu (32-bit) | |_____________________________|_____________________________| | | SUNWcpcux (64-bit) | |_____________________________|_____________________________| | Interface Stability | Evolving | |_____________________________|_____________________________|


nawk(1), perl(1), proc(1), truss(1), cpustat(1M), prstat(1), gethrtime(3C), cpc(3CPC), cpc_strtoevent(3CPC), cpc_count_usr_events(3CPC), libcpc(3LIB), libpctx(3LIB), proc(4), attributes(5). Sun Microelectronics UltraSPARC I&II User's Manual, January 1997, STP1031, Intel Architecture Software Developer's Manual, Volume 3: System Programmers Guide, 243192, SunOS 5.8 Last change: 14 Sep 1999 5