doc/oprofile.1

   1 .TH OPROFILE 1 "Fri 12 September 2014" "oprofile 1.0.0"
   2 .UC 4
   3 .SH NAME
   4 oprofile \- a system-wide profiler
   5 .SH SYNOPSIS
   6 .br
   7 .B opreport
   8 [
   9 .I options
  10 ]
  11 [ profile specification ]
  12 .br
  13 .B opannotate
  14 [
  15 .I options
  16 ]
  17 [ profile specification ]
  18 .br
  19 .B oparchive
  20 [
  21 .I options
  22 ]
  23 [ profile specification ]
  24 .br
  25 .B opgprof
  26 [
  27 .I options
  28 ]
  29 [ profile specification ]
  30 .br
  31 .SH DESCRIPTION
  32 OProfile is a profiling system for systems running Linux
  33 2.6 and greater. Profiling runs transparently in the background and profile
  34 data can be collected at any time. OProfile makes use of the hardware
  35 performance counters provided on Intel, AMD, and other processors,
  36 and uses a timer-interrupt based mechanism on CPUs without counters.
  37 OProfile can profile the whole system in high detail.
  38 .br
  39 For a gentle guide to using OProfile, please read the HTML documentation
  40 listed in SEE ALSO.
  41 .br
  42 .SH OPCONTROL
  43 .SH OPREPORT
  44 .B opreport
  45 gives image and symbol-based profile summaries for the whole system or
  46 a subset of binary images.
  47 .SH OPANNOTATE
  48 .B opannotate
  49 can produce annotated source or mixed source and assembly output.
  50 .SH OPARCHIVE
  51 .B oparchive
  52 produces oprofile archive for offline analysis
  53 .SH OPGPROF
  54 .B opgprof
  55 can produce a gprof-format profile for a single binary.
  56
  57 .SH PROFILE SPECIFICATIONS
  58 All of the post-profiling tools can take profile specifications,
  59 which is some combination of the following parameters. Enclosing
  60 part of a profile specification in curly braces { } can be used
  61 for differential profiles with
  62 .B opreport
  63 ; the braces
  64 .B must
  65 be surrounded by whitespace.
  66
  67 .TP
  68 .BI "archive:"archive
  69 Path to the archive to inspect, as generated by
  70 .B oparchive
  71 .br
  72 .TP
  73 .BI "session:"sessionlist
  74 A comma-separated list of session names to resolve in. Absence of this
  75 tag, unlike all others, means "the current session", equivalent to
  76 specifying "session:current".
  77 .br
  78 .TP
  79 .BI "session-exclude:"sessionlist
  80 A comma-separated list of sessions to exclude.
  81 .br
  82 .TP
  83 .BI "image:"imagelist
  84 A comma-separated list of image names to resolve. Each entry may be relative
  85 path, glob-style name, or full path, e.g.
  86 opreport 'image:/usr/bin/oprofiled,*op*,./oprofpp'
  87 .br
  88 .TP
  89 .BI "image-exclude:"imagelist
  90 Same as image:, but the matching images are excluded.
  91 .br
  92 .TP
  93 .BI "lib-image:"imagelist
  94 Same as image:, but only for images that are for
  95 a particular primary binary image (namely, an application). This only
  96 makes sense to use if you're using --separate.
  97 This includes kernel modules and the kernel when using
  98 --separate=kernel.
  99 .br
 100 .TP
 101 .BI "lib-image-exclude:"imagelist
 102 Same as <option>lib-image:</option>, but the matching images
 103 are excluded.
 104 .br
 105 .TP
 106 .BI "event:"eventname
 107 The symbolic event name to match on, e.g. event:DATA_MEM_REFS.
 108 .br
 109 .TP
 110 .BI "count:"eventcount
 111 The event count to match on, e.g. event:DATA_MEM_REFS count:30000.
 112 .br
 113 .TP
 114 .BI "unit-mask:"maskvalue
 115 The unit mask value of the event to match on, e.g. unit-mask:1.
 116 .br
 117 .TP
 118 .BI "cpu:"cpulist
 119 Only consider profiles for the given numbered CPU (starting from zero).
 120 This is only useful when using CPU profile separation.
 121 .br
 122 .TP
 123 .BI "tgid:"pidlist
 124 Only consider profiles for the given task groups. Unless some program is
 125 using threads, the task group ID of a process is the same as its process
 126 ID. This option corresponds to the POSIX notion of a thread group. This
 127 is only useful when using per-process profile separation.
 128 .br
 129 .TP
 130 .BI "tid:"tidlist
 131 Only consider profiles for the given threads. When using recent thread
 132 libraries, all threads in a process share the same task group ID, but
 133 have different thread IDs. You can use this option in combination with
 134 tgid: to restrict the results to particular threads within a process.
 135 This is only useful when using per-process profile separation.
 136
 137 .SH ENVIRONMENT
 138 No special environment variables are recognized by oprofile.
 139
 140 .SH FILES
 141 .TP
 142 .I /usr/local/share/doc/oprofile/oprofile.html
 143 OProfile user guide.
 144 .TP
 145 .I /usr/local/share/doc/oprofile/opreport.xsd
 146 Schema file for opreport XML output.
 147 .TP
 148 .I /usr/local/share/doc/oprofile/ophelp.xsd
 149 Schema file for ophelp XML output.
 150 .TP
 151 .I /usr/local/share/oprofile/
 152 Event description files used by OProfile.
 153 .TP
 154 .I <session-dir>/samples/operf.log
 155 The profiler log file.
 156 .TP
 157 .I <session-dir>/samples/current
 158 The location of the generated sample files.
 159
 160 .SH VERSION
 161 .TP
 162 This man page is current for oprofile-1.0.0.
 163
 164 .SH SEE ALSO
 165 .BR /usr/local/share/doc/oprofile/,
 166 .BR opreport(1),
 167 .BR opannotate(1),
 168 .BR oparchive(1),
 169 .BR opgprof(1),
 170 .BR gprof(1),
 171 .BR "CPU vendor architecture manuals"
 172
 173 .SH COPYRIGHT
 174 oprofile is Copyright (C) 1998-2004 University of Manchester, UK, John Levon,
 175 and others.
 176 OProfile is released under the GNU General Public License, Version 2,
 177 or (at your option) any later version.
 178 .SH AUTHORS
 179 John Levon <levon@movementarian.org> is the primary author. See the documentation
 180 for other contributors.