2. Using opcontrol

In this section we describe the configuration and control of the profiling system with opcontrol in more depth. See Section 1, “Using operf for a description of the preferred profiling method.

The opcontrol script has a default setup, but you can alter this with the options given below. In particular, you can select specific hardware events on which to base your profile. See Section 1, “Using operf for an introduction to hardware events and performance counter configuration. The event types and unit masks for your CPU are listed by opcontrol --list-events or ophelp.

The opcontrol script provides the following actions :

--init

Loads the OProfile module if required and makes the OProfile driver interface available.

--setup

Followed by list arguments for profiling set up. List of arguments saved in /root/.oprofile/daemonrc. Giving this option is not necessary; you can just directly pass one of the setup options, e.g. opcontrol --no-vmlinux.

--status

Show configuration information.

--start-daemon

Start the oprofile daemon without starting actual profiling. The profiling can then be started using --start. This is useful for avoiding measuring the cost of daemon startup, as --start is a simple write to a file in oprofilefs.

--start

Start data collection with either arguments provided by --setup or information saved in /root/.oprofile/daemonrc. Specifying the addition --verbose makes the daemon generate lots of debug data whilst it is running.

--dump

Force a flush of the collected profiling data to the daemon.

--stop

Stop data collection.

--shutdown

Stop data collection and kill the daemon.

--reset

Clears out data from current session, but leaves saved sessions.

--save=session_name

Save data from current session to session_name.

--deinit

Shuts down daemon. Unload the OProfile module and oprofilefs.

--list-events

List event types and unit masks.

--help

Generate usage messages.

There are a number of possible settings, of which, only --vmlinux (or --no-vmlinux) is required. These settings are stored in ~/.oprofile/daemonrc.

--buffer-size=num

Number of samples in kernel buffer. Buffer watershed needs to be tweaked when changing this value.

--buffer-watershed=num

Set kernel buffer watershed to num samples. When remain only buffer-size - buffer-watershed free entries remain in the kernel buffer, data will be flushed to the daemon. Most useful values are in the range [0.25 - 0.5] * buffer-size.

--cpu-buffer-size=num

Number of samples in kernel per-cpu buffer. If you profile at high rate, it can help to increase this if the log file show excessive count of samples lost due to cpu buffer overflow.

--event=[eventspec]

Use the given performance counter event to profile. See Section 4, “Specifying performance counter events” below.

--session-dir=dir_path

Create/use sample database out of directory dir_path instead of the default location (/var/lib/oprofile).

--separate=[none,lib,kernel,thread,cpu,all]

By default, every profile is stored in a single file. Thus, for example, samples in the C library are all accredited to the /lib/libc.o profile. However, you choose to create separate sample files by specifying one of the below options.

none No profile separation (default)
lib Create per-application profiles for libraries
kernel Create per-application profiles for the kernel and kernel modules
thread Create profiles for each thread and each task
cpu Create profiles for each CPU
all All of the above options

Note that --separate=kernel also turns on --separate=lib. When using --separate=kernel, samples in hardware interrupts, soft-irqs, or other asynchronous kernel contexts are credited to the task currently running. This means you will see seemingly nonsense profiles such as /bin/bash showing samples for the PPP modules, etc.

Using --separate=thread creates a lot of sample files if you leave OProfile running for a while; it's most useful when used for short sessions, or when using image filtering.

--callgraph=#depth

Enable call-graph sample collection with a maximum depth. Use 0 to disable callgraph profiling. NOTE: Callgraph support is available on a limited number of platforms at this time; for example:

  • x86 with 2.6 or higher kernel

  • ARM with 2.6 or higher kernel

  • PowerPC with 2.6.17 or higher kernel

--image=image,[images]|"all"

Image filtering. If you specify one or more absolute paths to binaries, OProfile will only produce profile results for those binary images. This is useful for restricting the sometimes voluminous output you may get otherwise, especially with --separate=thread. Note that if you are using --separate=lib or --separate=kernel, then if you specification an application binary, the shared libraries and kernel code are included. Specify the value "all" to profile everything (the default).

--vmlinux=file

vmlinux kernel image.

--no-vmlinux

Use this when you don't have a kernel vmlinux file, and you don't want to profile the kernel. This still counts the total number of kernel samples, but can't give symbol-based results for the kernel or any modules.

2.1. Examples

2.1.1. Intel performance counter setup

Here, we have a Pentium III running at 800MHz, and we want to look at where data memory references are happening most, and also get results for CPU time.

# opcontrol --event=CPU_CLK_UNHALTED:400000 --event=DATA_MEM_REFS:10000
# opcontrol --vmlinux=/boot/2.6.0/vmlinux
# opcontrol --start

2.1.2. Starting the daemon separately

Use --start-daemon to avoid the profiler startup affecting results.

# opcontrol --vmlinux=/boot/2.6.0/vmlinux
# opcontrol --start-daemon
# my_favourite_benchmark --init
# opcontrol --start ; my_favourite_benchmark --run ; opcontrol --stop

2.1.3. Separate profiles for libraries and the kernel

Here, we want to see a profile of the OProfile daemon itself, including when it was running inside the kernel driver, and its use of shared libraries.

# opcontrol --separate=kernel --vmlinux=/boot/2.6.0/vmlinux
# opcontrol --start
# my_favourite_stress_test --run
# opreport -l -p /lib/modules/2.6.0/kernel /usr/local/bin/oprofiled

2.1.4. Profiling sessions

It can often be useful to split up profiling data into several different time periods. For example, you may want to collect data on an application's startup separately from the normal runtime data. You can use the simple command opcontrol --save to do this. For example :

# opcontrol --save=blah

will create a sub-directory in $SESSION_DIR/samples containing the samples up to that point (the current session's sample files are moved into this directory). You can then pass this session name as a parameter to the post-profiling analysis tools, to only get data up to the point you named the session. If you do not want to save a session, you can do rm -rf $SESSION_DIR/samples/sessionname or, for the current session, opcontrol --reset.