toplev.man

.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.43.3.
.TH TOPLEV.PY "1" "October 2014" "toplev.py toplev" "User Commands"
.SH NAME
toplev.py \- manual page for toplev.py toplev
.SH DESCRIPTION
usage: toplev [options] perf\-arguments
.PP
Do cycle decomposition on a workload: estimate on which part of the
CPU pipeline it bottlenecks. The bottlenecks are expressed as a tree
with different levels.
.PP
Requires an Intel Sandy, Ivy Bridge, Haswell CPU.
It works best on Ivy Bridge currently.
On Sandy Bridge Server use Sandy Bridge (FORCECPU=snb)
.SH EXAMPLES

\&./toplev.py \-l2 program
measure program in level 2
.PP
\&./toplev.py \-a sleep X
measure whole system for X seconds
.PP
\&./toplev.py \-o logfile.csv \-x, \-p PID
measure pid PID, outputting in CSV format
.SS "optional arguments:"
.TP
\-h, \-\-help
show this help message and exit
.TP
\-\-verbose, \-v
Print all results even when below threshold
.TP
\-\-force
Force potentially broken configurations
.TP
\-\-kernel
Only measure kernel code
.TP
\-\-user
Only measure user code
.TP
\-\-print\-group, \-g
Print event group assignments
.TP
\-\-no\-desc
Don't print event descriptions
.TP
\-\-csv CSV, \-x CSV
Enable CSV mode with specified delimeter
.TP
\-\-interval INTERVAL, \-I INTERVAL
Enable interval mode with ms interval
.TP
\-\-output OUTPUT, \-o OUTPUT
Set output file
.TP
\-\-graph
Automatically graph interval output with tl\-barplot.py
.TP
\-\-title TITLE
Set title of graph
.TP
\-\-xkcd
Use xkcd plotting mode for graph
.TP
\-\-level LEVEL, \-l LEVEL
Measure upto level N (max 5)
.TP
\-\-metrics, \-m
Print extra metrics
.TP
\-\-sample, \-S
Suggest commands to sample for bottlenecks
(experimential)
.TP
\-\-raw, \-r
Print raw values
.TP
\-\-no\-group
Dont use groups
.TP
\-\-no\-multiplex
Do not multiplex, but run the workload multiple times
as needed. Requires reproducible workloads.
.TP
\-\-power
Display power metrics
.PP
Other perf arguments allowed (see the perf documentation)
After \-\- perf arguments conflicting with toplev can be used.
.PP
Some caveats:
.PP
The lower levels of the measurement tree are less reliable
than the higher levels.  They also rely on counter multi\-plexing,
and can not run each equation in a single group, which can cause larger
measurement errors with non steady state workloads
.PP
(If you don't understand this terminology; it means measurements
in higher levels are less accurate and it works best with programs that primarily
do the same thing over and over)
.PP
In this case it's recommended to measure the program only after
the startup phase by profiling globally or attaching later.
level 1 or running without \-d is generally the most reliable.
.PP
If the program is very reproducible \-\- such as a simple kernel \-\-
it is also possible to use \-\-no\-multiplex. In this case the
workload is rerun multiple times until all data is collected.
Do not use together with sleep.
.PP
One of the events (even used by level 1) requires a recent enough
kernel that understands its counter constraints.  3.10+ is safe.
.PP
Various older kernels (such as 2.6.32) can not schedule all groups
used by toplev correctly. In this case use \-\-no\-group (may cause
additional measurement errors)
.PP
In Hyper Threading mode toplev defaults to measuring the whole
system.
.PP
Recent kernels do not allow all events needed by level 3 or larger
in Hyper Threading mode due to a bug workaround. If that is needed
please see the github site for a kernel patch.
.PP
Other CPUs can be forced with FORCECPU=name
Valid CPU names: snb jkt ivb ivt hsw hsx slm