Chapter 6. Controlling the event counter

Table of Contents

1. Using ocount

1. Using ocount

This section describes in detail how ocount is used. Unless the --events option is specified, ocount will use the default event for your system. For most systems, the default event is some cycles-based event, assuming your processor type supports hardware performance counters. The event specification used for ocount is slightly different from that required for profiling -- a count value is not needed. You can see the event information for your CPU using ophelp. More information on event specification can be found at Section 4, “Specifying performance counter events”.

The ocount command syntax is:

ocount [ options ] [ --system-wide | --process-list <pids> | --thread-list <tids> | --cpu-list <cpus> [ command [ args ] ] ]

ocount has 5 run modes:

  • system-wide
  • process-list
  • thread-list
  • cpu-list
  • command

One and only one of these 5 run modes must be specified when you run ocount. If you run ocount using a run mode other than command [args], press Ctrl-c to stop it when finished counting (e.g., when the monitored process ends). If you background ocount (i.e., with ’&’) while using one these run modes, you must stop it in a controlled manner so that the data collection process can be shut down cleanly and final results can be displayed. Use kill -SIGINT <ocount-PID> for this purpose.

Following is a description of the ocount options.

command [args]

The command or application to be profiled. The [args] are the input arguments that the command or application requires. The command and its arguments must be positioned at the end of the command line, after all other ocount options.

--process-list / -p [PIDs]

Use this option to count events for one or more already-running applications, specified via a comma-separated list (PIDs). Event counts will be collected for all children of the passed process(es) as well.

--thread-list / -r [TIDs]

Use this option to count events for one or more already-running threads, specified via a comma-separated list (TIDs). Event counts will not be collected for any children of the passed thread(s).

--system-wide / -s

This option is for counting events for all processes running on your system. You must have root authority to run ocount in this mode.

--cpu-list / -C [CPUs]

This option is for counting events on a subset of processors on your system. You must have root authority to run ocount in this mode. This is a comma-separated list, where each element in the list may be either a single processor number or a range of processor numbers; for example: ’-C 2,3,4-11,15’.

--events / -e [event1[,event2[,...]]]

This option is for passing a comma-separated list of event specifications for counting. Each event spec is of the form:

name[:unitmask[:kernel[:user]]]

When no event specification is given, the default event for the running processor type will be used for counting. Use ophelp to list the available events for your processor type.

--separate-thread / -t

This option can be used in conjunction with either the --process-list or --thread-list option to display event counts on a per-thread (per-process) basis. Without this option, all counts are aggregated.

--separate-cpu / -c

This option can be used in conjunction with either the --system-wide or --cpu-list option to display event counts on a per-cpu basis. Without this option, all counts are aggregated.

--time-interval / -i num_seconds[:num_intervals]

Results collected for each time interval are printed every num_seconds instead of the default of one dump of cumulative event counts at the end of the run. If num_intervals is specified, ocount exits after the specified number of intervals occur.

--brief-format / -b

Use this option to print results in the following brief format:

                  [optional cpu or thread,]<event_name>,<count>,<percent_time_enabled>
                  [        <int>         ,]<  string  >,< u64 >,<     double         >
        

If --timer-interval is specified, a separate line formatted as

                  timestamp,<num_seconds_since_epoch>
        

is printed ahead of each dump of event counts.

--output-file / -f outfile_name

Results are written to outfile_name instead of interactively to the terminal.

--verbose / -V

Use this option to increase the verbosity of the output.

--version -v

Show ocount version.

--help / -h

Show a help message.