# operf

## NAME



           operf - Performance profiler tool for Linux
    


## SYNOPSIS



           **operf**[ _options_ ] [ --system-wide | --pid <pid> | [ command [ args
           ] ] ]
    


## DESCRIPTION



           Operf is the profiler tool provided with OProfile. Operf uses the
           Linux Performance Events Subsystem and, thus, does not require the
           obsolete oprofile kernel driver.
    
           By default, operf uses <current_dir>/oprofile_data as the session-
           dir and stores profiling data there.  You can change this by way
           of the _--session-dir_ option. The usual post-profiling analysis
           tools such as **opreport(1)** and **opannotate(1)** can be used to
           generate profile reports. Unless a _session-dir_ is specified, the
           post-processing analysis tools will search for samples in
           <current_dir>/oprofile_data first. If that directory does not
           exist, the post-processing tools use the standard session-dir of
           /var/lib/oprofile.
    
           Statistics, such as total samples received and lost samples, are
           written to the operf.log file that can be found in the
           <session_dir>/samples directory.
    


## RUN MODES



           One (and only one) of the following **run modes** must be specified:
    
           **command** _[args]_
                  The command or application to be profiled.  _args_ are the
                  input arguments that the command or application requires.
    
           **--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. If you run **operf**
                  **--pid** as a background job (i.e., with the &), you **must** stop
                  it in a controlled manner in order for it to process the
                  profile data it has collected.  Use **kill -SIGINT <operf-**
                  **PID > **for this purpose.
    
                  **Limitation:** When using this option to profile a multi-
                  threaded application that also forks new processes, be
                  aware that samples for processes that are forked before
                  profiling is started may not be recorded (depending on
                  timing of thread creation and when operf is started).
    
           **--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 for it 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, the user's
                  current working directory should be /root or a subdirectory
                  of /root to avoid storing sample data files in locations
                  accessible by regular users.
    


## OTHER OPTIONS



           **--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.
    
                  The kernel symbol information may be obtained from
                  /proc/kallsyms if the user does not specify a vmlinux file.
                  The symbol addresses are given in /proc/kallsyms if
                  permitted by the setting of /proc/sys/kernel/kptr_restrict.
    
                  If the _--vmlinux_ option is not used and kernel symbols
                  cannot be obtained from /proc/kallsyms, then all kernel
                  samples are attributed to "no-vmlinux", which is simply a
                  bucket to hold the samples and not an actual file.
    
           **--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]]]_
    
                  The _count_ value is used to control the sampling rate for
                  profiling; it is the number of events to occur between
                  samples. The rate is lowered by specifying a higher _count_
                  value — i.e., a higher number of events to occur between
                  samples.
    
                  You can specify _unitmask_ values using either a numerical
                  value (hex values _must_ begin with "0x") or a symbolic name
                  (if the _name= <um_name>_ field is shown in the **ophelp**
                  output). For some named unit masks, the hex value is not
                  unique; thus, OProfile tools enforce specifying such unit
                  masks value by name.  If no unit mask is specified, the
                  default unit mask value for the event is used.
    
                  The _kernel_ and _user_ parts of the event specification are
                  binary values ('1' or '0') indicating whether or not to
                  collect samples for kernel space and user space.
                  **Note:** In order to specify the _kernel/user_ bits, you must
                  also specify a _unitmask_ value, even if the processor type
                  (or the specified event) does not use unit masks — in which
                  case, use the value '0' to signify a null unit mask; for
                  example:
                     -e INST_RETIRED_ANY_P:100000:0:1:0
                                           ^      ^ ^ ^
                                           |      | | |--- '0': do not record
                  user space samples
                                           |      | |-- '1': record kernel
                  space samples
                                           |      |-- '0': the null unit mask
                                           |--count value
    
                  Event names for some IBM PowerPC systems include a __GRP <n>_
                  (group number) suffix. You can pass either the full event
                  name or the base event name (i.e., without the suffix) to
                  **operf.** If the base event name is passed, **operf** will
                  automatically choose an appropriate group number suffix for
                  the event; thus, OProfile post-processing tools will always
                  show real event names that include the group number suffix.
    
                  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.
    
           **--callgraph / -g**
                  This option enables the callgraph to be saved during
                  profiling. NOTE: The full callchain is recorded, so there
                  is no depth limit.
    
           **--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 conjunction with the '--system-
                  wide' option, the '--separate-thread' option 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 path 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.
    
                  **Note:** This option is **not** recommended to be used in
                  conjunction with the _--pid_ option for profiling multi-
                  threaded processes. Depending on the order of thread
                  creation (or forking of new processes), you may not get any
                  samples for the new threads/processes.
    
           **--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 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**
    
           **--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, or the special
                  value, 'all'.
    
           **--version / -v**
                  Show operf version.
    
           **--help / -h**
                  Display brief usage message.
    
           **--usage / -u**
                  Display brief usage message.
    


## EXAMPLE



           $ operf make
    


## VERSION



           This man page is current for oprofile-1.5.0git.
    


* * *