diff options
Diffstat (limited to 'tools/perf/Documentation')
| -rw-r--r-- | tools/perf/Documentation/perf-config.txt | 103 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf-evlist.txt | 3 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf-record.txt | 24 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf-report.txt | 41 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf-stat.txt | 34 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf-top.txt | 3 | ||||
| -rw-r--r-- | tools/perf/Documentation/tips.txt | 14 |
7 files changed, 215 insertions, 7 deletions
diff --git a/tools/perf/Documentation/perf-config.txt b/tools/perf/Documentation/perf-config.txt new file mode 100644 index 000000000000..b9ca1e304158 --- /dev/null +++ b/tools/perf/Documentation/perf-config.txt @@ -0,0 +1,103 @@ +perf-config(1) +============== + +NAME +---- +perf-config - Get and set variables in a configuration file. + +SYNOPSIS +-------- +[verse] +'perf config' -l | --list + +DESCRIPTION +----------- +You can manage variables in a configuration file with this command. + +OPTIONS +------- + +-l:: +--list:: + Show current config variables, name and value, for all sections. + +CONFIGURATION FILE +------------------ + +The perf configuration file contains many variables to change various +aspects of each of its tools, including output, disk usage, etc. +The '$HOME/.perfconfig' file is used to store a per-user configuration. +The file '$(sysconfdir)/perfconfig' can be used to +store a system-wide default configuration. + +Syntax +~~~~~~ + +The file consist of sections. A section starts with its name +surrounded by square brackets and continues till the next section +begins. Each variable must be in a section, and have the form +'name = value', for example: + + [section] + name1 = value1 + name2 = value2 + +Section names are case sensitive and can contain any characters except +newline (double quote `"` and backslash have to be escaped as `\"` and `\\`, +respectively). Section headers can't span multiple lines. + +Example +~~~~~~~ + +Given a $HOME/.perfconfig like this: + +# +# This is the config file, and +# a '#' and ';' character indicates a comment +# + + [colors] + # Color variables + top = red, default + medium = green, default + normal = lightgray, default + selected = white, lightgray + code = blue, default + addr = magenta, default + root = white, blue + + [tui] + # Defaults if linked with libslang + report = on + annotate = on + top = on + + [buildid] + # Default, disable using /dev/null + dir = ~/.debug + + [annotate] + # Defaults + hide_src_code = false + use_offset = true + jump_arrows = true + show_nr_jumps = false + + [help] + # Format can be man, info, web or html + format = man + autocorrect = 0 + + [ui] + show-headers = true + + [call-graph] + # fp (framepointer), dwarf + record-mode = fp + print-type = graph + order = caller + sort-key = function + +SEE ALSO +-------- +linkperf:perf[1] diff --git a/tools/perf/Documentation/perf-evlist.txt b/tools/perf/Documentation/perf-evlist.txt index 1ceb3700ffbb..6f7200fb85cf 100644 --- a/tools/perf/Documentation/perf-evlist.txt +++ b/tools/perf/Documentation/perf-evlist.txt @@ -32,6 +32,9 @@ OPTIONS --group:: Show event group information. +--trace-fields:: + Show tracepoint field names. + SEE ALSO -------- linkperf:perf-record[1], linkperf:perf-list[1], diff --git a/tools/perf/Documentation/perf-record.txt b/tools/perf/Documentation/perf-record.txt index e630a7d2c348..3a1a32f5479f 100644 --- a/tools/perf/Documentation/perf-record.txt +++ b/tools/perf/Documentation/perf-record.txt @@ -207,11 +207,23 @@ comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0- In per-thread mode with inheritance mode on (default), samples are captured only when the thread executes on the designated CPUs. Default is to monitor all CPUs. +-B:: +--no-buildid:: +Do not save the build ids of binaries in the perf.data files. This skips +post processing after recording, which sometimes makes the final step in +the recording process to take a long time, as it needs to process all +events looking for mmap records. The downside is that it can misresolve +symbols if the workload binaries used when recording get locally rebuilt +or upgraded, because the only key available in this case is the +pathname. You can also set the "record.build-id" config variable to +'skip to have this behaviour permanently. + -N:: --no-buildid-cache:: Do not update the buildid cache. This saves some overhead in situations where the information in the perf.data file (which includes buildids) -is sufficient. +is sufficient. You can also set the "record.build-id" config variable to +'no-cache' to have the same effect. -G name,...:: --cgroup name,...:: @@ -314,11 +326,17 @@ This option sets the time out limit. The default value is 500 ms. Record context switch events i.e. events of type PERF_RECORD_SWITCH or PERF_RECORD_SWITCH_CPU_WIDE. ---clang-path:: +--clang-path=PATH:: Path to clang binary to use for compiling BPF scriptlets. +(enabled when BPF support is on) ---clang-opt:: +--clang-opt=OPTIONS:: Options passed to clang when compiling BPF scriptlets. +(enabled when BPF support is on) + +--vmlinux=PATH:: +Specify vmlinux path which has debuginfo. +(enabled when BPF prologue is on) SEE ALSO -------- diff --git a/tools/perf/Documentation/perf-report.txt b/tools/perf/Documentation/perf-report.txt index 5ce8da1e1256..8a301f6afb37 100644 --- a/tools/perf/Documentation/perf-report.txt +++ b/tools/perf/Documentation/perf-report.txt @@ -117,6 +117,30 @@ OPTIONS And default sort keys are changed to comm, dso_from, symbol_from, dso_to and symbol_to, see '--branch-stack'. + If the data file has tracepoint event(s), following (dynamic) sort keys + are also available: + trace, trace_fields, [<event>.]<field>[/raw] + + - trace: pretty printed trace output in a single column + - trace_fields: fields in tracepoints in separate columns + - <field name>: optional event and field name for a specific field + + The last form consists of event and field names. If event name is + omitted, it searches all events for matching field name. The matched + field will be shown only for the event has the field. The event name + supports substring match so user doesn't need to specify full subsystem + and event name everytime. For example, 'sched:sched_switch' event can + be shortened to 'switch' as long as it's not ambiguous. Also event can + be specified by its index (starting from 1) preceded by the '%'. + So '%1' is the first event, '%2' is the second, and so on. + + The field name can have '/raw' suffix which disables pretty printing + and shows raw field value like hex numbers. The --raw-trace option + has the same effect for all dynamic sort keys. + + The default sort keys are changed to 'trace' if all events in the data + file are tracepoint. + -F:: --fields=:: Specify output field - multiple keys can be specified in CSV format. @@ -170,17 +194,18 @@ OPTIONS Dump raw trace in ASCII. -g:: ---call-graph=<print_type,threshold[,print_limit],order,sort_key,branch>:: +--call-graph=<print_type,threshold[,print_limit],order,sort_key[,branch],value>:: Display call chains using type, min percent threshold, print limit, - call order, sort key and branch. Note that ordering of parameters is not - fixed so any parement can be given in an arbitraty order. One exception - is the print_limit which should be preceded by threshold. + call order, sort key, optional branch and value. Note that ordering of + parameters is not fixed so any parement can be given in an arbitraty order. + One exception is the print_limit which should be preceded by threshold. print_type can be either: - flat: single column, linear exposure of call chains. - graph: use a graph tree, displaying absolute overhead rates. (default) - fractal: like graph, but displays relative rates. Each branch of the tree is considered as a new profiled object. + - folded: call chains are displayed in a line, separated by semicolons - none: disable call chain display. threshold is a percentage value which specifies a minimum percent to be @@ -204,6 +229,11 @@ OPTIONS - branch: include last branch information in callgraph when available. Usually more convenient to use --branch-history for this. + value can be: + - percent: diplay overhead percent (default) + - period: display event period + - count: display event count + --children:: Accumulate callchain of children to parent entry so that then can show up in the output. The output will have a new "Children" column @@ -365,6 +395,9 @@ include::itrace.txt[] --socket-filter:: Only report the samples on the processor socket that match with this filter +--raw-trace:: + When displaying traceevent output, do not use print fmt or plugins. + include::callchain-overhead-calculation.txt[] SEE ALSO diff --git a/tools/perf/Documentation/perf-stat.txt b/tools/perf/Documentation/perf-stat.txt index 4e074a660826..52ef7a9d50aa 100644 --- a/tools/perf/Documentation/perf-stat.txt +++ b/tools/perf/Documentation/perf-stat.txt @@ -10,6 +10,8 @@ SYNOPSIS [verse] 'perf stat' [-e <EVENT> | --event=EVENT] [-a] <command> 'perf stat' [-e <EVENT> | --event=EVENT] [-a] -- <command> [<options>] +'perf stat' [-e <EVENT> | --event=EVENT] [-a] record [-o file] -- <command> [<options>] +'perf stat' report [-i file] DESCRIPTION ----------- @@ -22,6 +24,11 @@ OPTIONS <command>...:: Any command you can specify in a shell. +record:: + See STAT RECORD. + +report:: + See STAT REPORT. -e:: --event=:: @@ -159,6 +166,33 @@ filter out the startup phase of the program, which is often very different. Print statistics of transactional execution if supported. +STAT RECORD +----------- +Stores stat data into perf data file. + +-o file:: +--output file:: +Output file name. + +STAT REPORT +----------- +Reads and reports stat data from perf data file. + +-i file:: +--input file:: +Input file name. + +--per-socket:: +Aggregate counts per processor socket for system-wide mode measurements. + +--per-core:: +Aggregate counts per physical processor for system-wide mode measurements. + +-A:: +--no-aggr:: +Do not aggregate counts across all monitored CPUs. + + EXAMPLES -------- diff --git a/tools/perf/Documentation/perf-top.txt b/tools/perf/Documentation/perf-top.txt index 556cec09bf50..b0e60e17db38 100644 --- a/tools/perf/Documentation/perf-top.txt +++ b/tools/perf/Documentation/perf-top.txt @@ -230,6 +230,9 @@ Default is to monitor all CPUS. The various filters must be specified as a comma separated list: --branch-filter any_ret,u,k Note that this feature may not be available on all processors. +--raw-trace:: + When displaying traceevent output, do not use print fmt or plugins. + INTERACTIVE PROMPTING KEYS -------------------------- diff --git a/tools/perf/Documentation/tips.txt b/tools/perf/Documentation/tips.txt new file mode 100644 index 000000000000..a1c10e360db5 --- /dev/null +++ b/tools/perf/Documentation/tips.txt @@ -0,0 +1,14 @@ +For a higher level overview, try: perf report --sort comm,dso +Sample related events with: perf record -e '{cycles,instructions}:S' +Compare performance results with: perf diff [<old file> <new file>] +Boolean options have negative forms, e.g.: perf report --no-children +Customize output of perf script with: perf script -F event,ip,sym +Generate a script for your data: perf script -g <lang> +Save output of perf stat using: perf stat record <target workload> +Create an archive with symtabs to analyse on other machine: perf archive +Search options using a keyword: perf report -h <keyword> +Use parent filter to see specific call path: perf report -p <regex> +List events using substring match: perf list <keyword> +To see list of saved events and attributes: perf evlist -v +Use --symfs <dir> if your symbol files are in non-standard locations +To see callchains in a more compact form: perf report -g folded |