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 speci-
     fied, 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
           Specifies 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    Enables debug mode.

     -e    Follows  all  exec(2),  or  execve(2)  system   calls.
           Without  this  option,  cputrack  terminates  when the
           process image is overlaid with a new executable.

     -f    Follows all children created by fork(2), fork1(2),  or
           vfork(2) system calls.

     -h    Prints an extended help message  on  how  to  use  the
           utility  and  how  to  program the processor-dependent

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

     -N count
           Specifies  the  maximum  number  of  CPU   performance
           counter samples to take before exiting.

     -o outfile
           Specifies file to be used for the cputrack output.

     -p pid
           Interprets the argument as the process ID of an exist-
           ing process to which process counter context should be
           attached and monitored.

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

     -T interval
           Specifies the interval between CPU performance counter
           samples  in  seconds.  Very  small intervals may cause
           some samples to be skipped. See WARNINGS.

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

     For the -T interval option,  if  interval  is  specified  as
     zero,  no  periodic  sampling  is performed. The performance
     counters are only sampled when the process creates  or  des-
     troys an LWP, or it invokes fork(2), exec(2), or exit(2).


     Example 1: Using performance counters to count clock cycles

     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.

     example% 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: Counting external cache references and hits

     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. Notice that the
     explicit pic0 and pic1 names can be omitted where there  are
     no ambiguities.

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

     Example 3: Counting instructions

     This example shows how many instructions  were  executed  in
     the  application  and  in  the kernel to print the date on a
     Pentium machine:

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

     If cputrack 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:

     cputrack: 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  solu-

     If a short interval is requested, cputrack may not  be  able
     to  keep up with the desired sample rate. In this case, some
     samples may be dropped.


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

    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | Availability                | SUNWcpcu (32-bit)           |
    |                             | SUNWcpcux (64-bit)          |
    | Interface Stability         | Evolving                    |


     nawk(1),    perl(1),    proc(1),    truss(1),    prstat(1M),
     cpustat(1M), exec(2), exit(2), fork(2), setuid(2), vfork(2),
     gethrtime(3C),         cpc(3CPC),          cpc_access(3CPC),
     cpc_count_usr_events(3CPC),            cpc_strtoevent(3CPC),
     libcpc(3LIB), libpctx(3LIB), proc(4), attributes(5)

     Sun Microsystems UltraSPARC IIi and III Cu (v.2.2.1)  User's
     Manuals,              1997             and             2004,

Man(1) output converted with man2html