path: root/doc/oprofile.1

.TH OPROFILE 1 "Mon 20 July 2020" "oprofile 1.4.0"
.UC 4
.SH NAME
oprofile \- a statistical profiler for Linux systems, capable of profiling all running code
at low overhead; also included is a set of post-profiling analysis tools, as well as a simple
event counting tool
.SH SYNOPSIS
.br
.B operf
[
.I options
]
.br
.B ocount
[
.I options
]
.br
.B opreport
[
.I options
]
[ profile specification ]
.br
.B opannotate
[
.I options
]
[ profile specification ]
.br
.B oparchive
[
.I options
]
[ profile specification ]
.br
.B opgprof
[
.I options
]
[ profile specification ]
.br
.SH DESCRIPTION
OProfile is a profiling system for systems running Linux
2.6.31 and greater. OProfile makes use of the hardware
performance counters provided on Intel, AMD, and other processors.
OProfile can profile a selected program or process or the whole system.
OProfile can also be used to collect cumulative event counts at the
application, process, or system level.
.br
For a gentle guide to using OProfile, please read the HTML documentation
listed in SEE ALSO.
.br
.SH OPERF
.B operf
is a performance profiler tool for Linux.
.SH OCOUNT
.B ocount
is an event counting tool for Linux.
.SH OPREPORT
.B opreport
gives image and symbol-based profile summaries for the whole system or
a subset of binary images.
.SH OPANNOTATE
.B opannotate
can produce annotated source or mixed source and assembly output.
.SH OPARCHIVE
.B oparchive
produces oprofile archive for offline analysis
.SH OPGPROF
.B opgprof
can produce a gprof-format profile for a single binary.

.SH PROFILE SPECIFICATIONS
Various optional profile specifications may be used with the
post-profiling tools. A profile specification is some combination of the parameters
listed below. (
.BR Note :
Enclosing part of a profile specification in curly braces { } can be used
for differential profiles with
.BR opreport ,
but the braces
.B must
be surrounded by whitespace.)

.TP
.BI "archive:"archive
Path to the archive to inspect, as generated by
.B oparchive
.br
.TP
.BI "session:"sessionlist
A comma-separated list of session names to resolve in. Absence of this
tag, unlike all others, means "the current session", equivalent to
specifying "session:current".
.br
.TP
.BI "session-exclude:"sessionlist
A comma-separated list of sessions to exclude.
.br
.TP
.BI "image:"imagelist
A comma-separated list of image names to resolve. Each entry may be relative
path, glob-style name, or full path, e.g.
opreport 'image:/usr/bin/operf,*op*,./oprofpp'
.br
.TP
.BI "image-exclude:"imagelist
Same as image:, but the matching images are excluded.
.br
.TP
.BI "lib-image:"imagelist
Same as image:, but only for images that are for
a particular primary binary image (namely, an application). This only
makes sense to use if you're using --separate.
This includes kernel modules and the kernel when using
--separate=kernel.
.br
.TP
.BI "lib-image-exclude:"imagelist
Same as <option>lib-image:</option>, but the matching images
are excluded.
.br
.TP
.BI "event:"eventname
The symbolic event name to match on, e.g. event:DATA_MEM_REFS.
.br
.TP
.BI "count:"eventcount
The event count to match on, e.g. event:DATA_MEM_REFS count:30000.
.br
.TP
.BI "unit-mask:"maskvalue
The unit mask value of the event to match on, e.g. unit-mask:1.
.br
.TP
.BI "cpu:"cpulist
Only consider profiles for the given numbered CPU (starting from zero).
This is only useful when using CPU profile separation.
.br
.TP
.BI "tgid:"pidlist
Only consider profiles for the given task groups. Unless some program is
using threads, the task group ID of a process is the same as its process
ID. This option corresponds to the POSIX notion of a thread group. This
is only useful when using per-process profile separation.
.br
.TP
.BI "tid:"tidlist
Only consider profiles for the given threads. When using recent thread
libraries, all threads in a process share the same task group ID, but
have different thread IDs. You can use this option in combination with
tgid: to restrict the results to particular threads within a process.
This is only useful when using per-process profile separation.

.SH ENVIRONMENT
No special environment variables are recognized by OProfile.

.SH FILES
.TP
.I /usr/local/share/doc/oprofile/oprofile.html
OProfile user guide.
.TP
.I /usr/local/share/doc/oprofile/opreport.xsd
Schema file for opreport XML output.
.TP
.I /usr/local/share/doc/oprofile/ophelp.xsd
Schema file for ophelp XML output.
.TP
.I /usr/local/share/oprofile/
Event description files used by OProfile.
.TP
.I <session-dir>/samples/operf.log
The profiler log file.
.TP
.I <session-dir>/samples/current
The location of the generated sample files.

.SH VERSION
.TP
This man page is current for oprofile-1.4.0.

.SH SEE ALSO
.BR /usr/local/share/doc/oprofile/,
.BR operf(1),
.BR ocount(1),
.BR opreport(1),
.BR opannotate(1),
.BR oparchive(1),
.BR opgprof(1),
.BR gprof(1),
.BR "CPU vendor architecture manuals"

.SH COPYRIGHT
oprofile is Copyright (C) 1998-2004 University of Manchester, UK, John Levon,
and others.
OProfile is released under the GNU General Public License, Version 2,
or (at your option) any later version.
.SH AUTHORS
John Levon <levon@movementarian.org> is the primary author. See the documentation
for other contributors.