Chapter 3. Controlling the profiler

Table of Contents

1. Using operf
2. Using opcontrol
2.1. Examples
3. Setting up the JIT profiling feature
3.1. JVM instrumentation
4. Using oprof_start
5. Configuration details
5.1. Hardware performance counters
5.2. OProfile in timer interrupt mode
5.3. Pentium 4 support
5.4. Intel Itanium 2 support
5.5. PowerPC64 support
5.6. Cell Broadband Engine support
5.7. AMD64 (x86_64) Instruction-Based Sampling (IBS) support
5.8. IBM System z hardware sampling support
5.9. Dangerous counter settings

1. Using operf

This section describes in detail how operf is used to control profiling. Unless otherwise directed, operf will profile using 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. If your hardware does support performance counters, you can specify something other than the default hardware event on which to profile. The performance monitor counters can be programmed to count various hardware events, such as cache misses or MMX operations. The event chosen for each counter is reflected in the profile data collected by OProfile: functions and binaries at the top of the profiles reflect that most of the chosen events happened within that code.

Additionally, each counter is programmed with a "count" value, which corresponds to how detailed the profile is. The lower the value, the more frequently profile samples are taken. You can choose to sample only kernel code, user-space code, or both (both is the default). Finally, some events have a "unit mask" -- this is a value that further restricts the types of event that are counted. You can see the event types and unit masks for your CPU using ophelp. More information on event specification can be found at Section 4, “Specifying performance counter events”.

The operf command syntax is:

operf [ options ] [ --system-wide | --pid=<PID> | [ command [ args ] ] ]

When profiling an application using either the command or --pid option of operf, forks and execs of the profiled process will also be profiled. The samples from an exec'ed process will be attributed to the executable binary run by that process. See Section 7, “Using operf to profile fork/execs”

Following is a description of the operf options.

command [args]

The command or application to be profiled. The[args] are the input arguments that the command or application requires. Either command, --pid or --system-wide is required, but cannot be used simultaneously.

--pid / -p [PID]

This option enables operf to profile a running application. PID should be the process ID of the process you wish to profile. When finished profiling (e.g., when the profiled process ends), press Ctrl-c to stop operf.

--system-wide / -s

This option is for performing a system-wide profile. You must have root authority to run operf in this mode. When finished profiling, Ctrl-C to stop operf. If you run operf --system-wide as a background job (i.e., with the &), you must stop it in a controlled manner in order to process the profile data it has collected. Use kill -SIGINT <operf-PID> for this purpose. It is recommended that when running operf with this option, your current working directory should be /root or a subdirectory of /root to avoid storing sample data files in locations accessible by regular users.

--vmlinux / k [vmlinux_path]

A vmlinux file that matches the running kernel that has symbol and/or debuginfo. Kernel samples will be attributed to this binary, allowing post-processing tools (like opreport) to attribute samples to the appropriate kernel symbols. If this option is not specified, all kernel samples will be attributed to a pseudo binary named "no-vmlinux".

--callgraph / -g

This option enables the callgraph to be saved during profiling. NOTE: The full callchain is recorded, so there is no depth limit.

--append / -a

By default, operf moves old profile data from <session_dir>/samples/current to <session_dir>/samples/previous. If a 'previous' profile already existed, it will be replaced. If the --append option is passed, old profile data in 'current' is left in place and new profile data will be added to it, and the 'previous' profile (if one existed) will remain untouched. To access the 'previous' profile, simply add a session specification to the normal invocation of oprofile post-processing tools; for example:

opreport session:previous

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

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

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

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

--separate-thread / -t

This option categorizes samples by thread group ID (tgid) and thread ID (tid). The --separate-thread option is useful for seeing per-thread samples in multi-threaded applications. When used in conjuction with the --system-wide option, --separate-thread is also useful for seeing per-process (i.e., per-thread group) samples for the case where multiple processes are executing the same program during a profiling run.

--separate-cpu / -c

This option categorizes samples by cpu.

--session-dir / -d [path]

This option specifies the session directory to hold the sample data. If not specified, the data is saved in the oprofile_data directory on the current path.

---lazy-conversion / -l

Use this option to reduce the overhead of operf during profiling. Normally, profile data received from the kernel is converted to OProfile format during profiling time. This is typically not an issue when profiling a single application. But when using the --system-wide option, this on-the-fly conversion process can cause noticeable overhead, particularly on busy multi-processor systems. The --lazy-conversion option directs operf to wait until profiling is completed to do the conversion of profile data.

--verbose / -V [level]

A comma-separated list of debugging control values used to increase the verbosity of the output. Valid values are: debug, record, convert, misc, sfile, arcs, and the special value, 'all'.

--version -v

Show operf version.

--help / -h

Show a help message.