TOPLEV.PY(1)

NAME
toplev.py - manual page for toplev.py toplev

DESCRIPTION
usage: toplev [options] perf-arguments

Estimate on which part of the CPU pipeline a workload bottlenecks using the TopDown model. The bottlenecks are expressed as a tree with different levels. Requires a modern Intel CPU.

ENVIRONMENT

--force-cpu {snb,jkt,ivb,ivt,hsw,hsx,slm,bdw,bdx,simple,skl,knl,skx,clx,icl}
    Force CPU type

--force-topology findsysoutput
    Use specified topology file (find /sys/devices)

--force-cpuinfo cpuinfo
    Use specified cpuinfo file (/proc/cpuinfo)

--force-hypervisor
    Assume running under hypervisor (no uncore, no offcore, no PEBS)

--no-uncore
    Disable uncore events

--no-check
    Do not check that PMU units exist

  Additional information:

--print-group, -g
    Print event group assignments

--raw
    Print raw values

--valcsv VALCSV, -V VALCSV
    Write raw counter values into CSV file

--stats
    Show statistics on what events counted

  Sampling:

--show-sample
    Show command line to rerun workload with sampling

--run-sample
    Automatically rerun workload with sampling

--sample-args SAMPLE_ARGS
    Extra rguments to pass to perf record for sampling. Use + to specify -

--sample-repeat SAMPLE_REPEAT
    Repeat measurement and sampling N times. This interleaves counting and sampling. Useful for background collection with -a sleep X.

--sample-basename SAMPLE_BASENAME
    Base name of sample perf.data files

Other perf arguments allowed (see the perf documentation) After -- perf arguments conflicting with toplev can be used.

Some caveats:

toplev defaults to measuring the full system and show data for all CPUs. Use taskset to limit the workload to known CPUs if needed. In some cases (idle system, single threaded workload) --single-thread can also be used.

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

(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)

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.

toplev needs a new enough perf tool and has specific requirements on the kernel. See http://github.com/andikleen/pmu-tools/wiki/toplev-kernel-support

Other CPUs can be forced with FORCECPU=name This usually requires setting the correct event map with EVENTMAP=... The topology can be overriden with TOPOLOGY=file (sysfs filenames) and CPUINFO=file (/proc/cpuinfo replacement) Valid CPU names: snb jkt ivb ivt hsw hsx slm bdw bdx simple skl knl skx clx icl

EXAMPLES
toplev.py -l2 program measure whole system in level 2 while program is running

toplev.py -l1 --single-thread program measure single threaded program. system must be idle.

toplev.py -l3 --no-desc -I 100 -x, sleep X measure whole system for X seconds every 100ms, outputting in CSV format.

toplev.py --all --core C0 taskset -c 0,1 program Measure program running on core 0 with all nodes and metrics enables

  optional arguments:

-h, --help
    show this help message and exit

  General operation:

--interval INTERVAL, -I INTERVAL
    Measure every ms instead of only once

--no-multiplex
    Do not multiplex, but run the workload multiple times as needed. Requires reproducible workloads.

--single-thread, -S
    Measure workload as single thread. Workload must run single threaded. In SMT mode other thread must be idle.

--fast, -F
    Skip sanity checks to optimize CPU consumption

--import _IMPORT
    Import specified perf stat output file instead of running perf. Must be for same cpu, same arguments, same /proc/cpuinfo, same topology, unless overriden

--gen-script
    Generate script to collect perfmon information for --import later

  Measurement filtering:

--kernel
    Only measure kernel code

--user
    Only measure user code

--core CORE
    Limit output to cores. Comma list of Sx-Cx-Tx. All parts optional.

  Select events:

--level LEVEL, -l LEVEL
    Measure upto level N (max 6)

--metrics, -m
    Print extra metrics

--sw
    Measure perf Linux metrics

--no-util
    Do not measure CPU utilization

--tsx
    Measure TSX metrics

--all
    Measure everything available

--frequency
    Measure frequency

--power
    Display power metrics

--nodes NODES
    Include or exclude nodes (with + to add, -|^ to remove, comma separated list, wildcards allowed)

--reduced
    Use reduced server subset of nodes/metrics

--metric-group METRIC_GROUP
    Add (+) or remove (-|^) metric groups of metrics, comma separated list from --list-metric-groups.

  Query nodes:

--list-metrics
    List all metrics

--list-nodes
    List all nodes

--list-metric-groups
    List metric groups

--list-all
    List every supported node/metric/metricgroup

  Workarounds:

--no-group
    Dont use groups

--force-events
    Assume kernel supports all events. May give wrong results.

--ignore-errata
    Do not disable events with errata

--handle-errata
    Disable events with errata

  Output:

--per-core
    Aggregate output per core

--per-socket
    Aggregate output per socket

--per-thread
    Aggregate output per CPU thread

--global
    Aggregate output for all CPUs

--no-desc
    Do not print event descriptions

--desc
    Force event descriptions

--verbose, -v
    Print all results even when below threshold or exceeding boundaries. Note this can result in bogus values, as the TopDown methodology relies on thresholds to correctly characterize workloads.

--csv CSV, -x CSV
    Enable CSV mode with specified delimeter

--output OUTPUT, -o OUTPUT
    Set output file

--split-output
    Generate multiple output files, one for each specified aggregation option (with -o)

--graph
    Automatically graph interval output with tl-barplot.py

--graph-cpu GRAPH_CPU
    CPU to graph using --graph

--title TITLE
    Set title of graph

--quiet
    Avoid unnecessary status output

--long-desc
    Print long descriptions instead of abbreviated ones.

--columns
    Print CPU output in multiple columns for each node

--summary
    Print summary at the end. Only useful with -I

--no-area
    Hide area column

--perf-output PERF_OUTPUT
    Save perf stat output in specified file

--no-perf
    Don't print perf command line

--print
    Only print perf command line. Don't run