lkml.org 
[lkml]   [2015]   [Apr]   [18]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
From
Subject[PATCH] perf tools: Document --children option in more detail
Date
As the --children option changes the output of perf report (and perf
top) it sometimes confuses users. Add more words and examples to help
understanding of the option's behavior - and how to disable it ;-).

Cc: Taeung Song <treeze.taeung@gmail.com>
Signed-off-by: Namhyung Kim <namhyung@kernel.org>
---
tools/perf/Documentation/overhead.txt | 94 ++++++++++++++++++++++++++++++++
tools/perf/Documentation/perf-report.txt | 4 ++
tools/perf/Documentation/perf-top.txt | 3 +-
3 files changed, 100 insertions(+), 1 deletion(-)
create mode 100644 tools/perf/Documentation/overhead.txt

diff --git a/tools/perf/Documentation/overhead.txt b/tools/perf/Documentation/overhead.txt
new file mode 100644
index 000000000000..a04bc2087956
--- /dev/null
+++ b/tools/perf/Documentation/overhead.txt
@@ -0,0 +1,94 @@
+Overhead calculation
+--------------------
+The overhead can be shown in two columns as 'Children' and 'Self' when
+perf collects callchains. The self overhead is simply calculated by
+adding all period values of the entry - usually a function (symbol).
+This is the value that perf shows traditionally and sum of the all
+self overhead should be 100%.
+
+The children overhead is calculated by adding all period values of the
+child functions so that it can show the total overhead of the higher
+level functions. The children here means that functions called from
+another function.
+
+It might confusing that the sum of the all children overhead exceeds
+100%. But with this enabled, users can find which function has most
+overhead even if samples are spread over the children.
+
+Let me see you an example; there’re three functions like below.
+
+-----------------------
+void foo(void) {
+ /* something */
+}
+
+bar(void) {
+ /* do something */
+ foo();
+}
+
+int main(void) {
+ bar()
+ return 0;
+}
+-----------------------
+
+In this case 'foo' is a child of 'bar', and 'bar' is an immediate
+child of 'main' so 'foo' also is a child of 'main'. In other words,
+'main' is a parent of 'foo' and 'bar'. and 'bar' is a parent of 'foo'.
+
+Suppose all samples are recorded in the 'foo' and 'bar' only. When
+you record with callchain you'll see something like below in the usual
+(self-overhead-only) output of the perf report:
+
+----------------------------------
+Overhead Symbol
+........ .....................
+ 60.00% foo
+ |
+ --- foo
+ bar
+ main
+ __libc_start_main
+
+ 40.00% bar
+ |
+ --- bar
+ main
+ __libc_start_main
+----------------------------------
+
+When --children option is enabled, the (self) overhead of children (in
+this case foo and bar) will be added to its parent to calculate the
+children overhead. In this case we'll see somethink like below:
+
+-------------------------------------------
+Children Self Symbol
+........ ........ ....................
+ 100.00% 0.00% __libc_start_main
+ |
+ --- __libc_start_main
+
+ 100.00% 0.00% main
+ |
+ --- main
+ __libc_start_main
+
+ 100.00% 40.00% bar
+ |
+ --- bar
+ main
+ __libc_start_main
+
+ 60.00% 60.00% foo
+ |
+ --- foo
+ bar
+ main
+ __libc_start_main
+-------------------------------------------
+
+Please note that since v3.16 the children overhead will be shown by
+default and the output will be sorted by the values, users can disable
+it by specifing --no-children option on the command line, or by adding
++report.children = false+ or +top.children = false+ config option.
diff --git a/tools/perf/Documentation/perf-report.txt b/tools/perf/Documentation/perf-report.txt
index 4879cf638824..bd97e5c3c9b6 100644
--- a/tools/perf/Documentation/perf-report.txt
+++ b/tools/perf/Documentation/perf-report.txt
@@ -193,6 +193,7 @@ OPTIONS
Accumulate callchain of children to parent entry so that then can
show up in the output. The output will have a new "Children" column
and will be sorted on the data. It requires callchains are recorded.
+ See `overhead calculation' section for more details.

--max-stack::
Set the stack depth limit when parsing the callchain, anything
@@ -323,6 +324,9 @@ OPTIONS
--header-only::
Show only perf.data header (forces --stdio).

+
+include::overhead.txt[]
+
SEE ALSO
--------
linkperf:perf-stat[1], linkperf:perf-annotate[1]
diff --git a/tools/perf/Documentation/perf-top.txt b/tools/perf/Documentation/perf-top.txt
index 3265b1070518..526d6bebec1f 100644
--- a/tools/perf/Documentation/perf-top.txt
+++ b/tools/perf/Documentation/perf-top.txt
@@ -168,7 +168,7 @@ Default is to monitor all CPUS.
Accumulate callchain of children to parent entry so that then can
show up in the output. The output will have a new "Children" column
and will be sorted on the data. It requires -g/--call-graph option
- enabled.
+ enabled. See `overhead calculation' section for more details.

--max-stack::
Set the stack depth limit when parsing the callchain, anything
@@ -234,6 +234,7 @@ INTERACTIVE PROMPTING KEYS

Pressing any unmapped key displays a menu, and prompts for input.

+include::overhead.txt[]

SEE ALSO
--------
--
2.3.5


\
 
 \ /
  Last update: 2015-04-18 19:41    [W:0.054 / U:1.040 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site