Skip to contentSkip to conversation

perf tools: Document --children option in more detail

PATCH Superseded Namhyung Kim 2 participants 3 messages Apr 18, 2015 – Apr 20, 2015 perf events

v1 of 4 Superseded Latest is v4 →

lore
Share & tools
lore

Namhyung Kim

author maintainer
#0 lore raw

PATCH 1/1 perf tools: Document --children option in more detail

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 ;-).

---
 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
tools/perf/Documentation/overhead.txt new file +94 -0
new file mode 100644
index 000000000000..a04bc2087956
@@ -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.
tools/perf/Documentation/perf-report.txt +4 -0
index 4879cf638824..bd97e5c3c9b6 100644
@@ -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]
tools/perf/Documentation/perf-top.txt +2 -1
index 3265b1070518..526d6bebec1f 100644
@@ -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
 --------
Signature · 1 line
2.3.5
#1 lore raw

tools/perf/Documentation/overhead.txt line 16

Quoted 3 lines · Namhyung Kim
tools/perf/Documentation/overhead.txt new file +3 -0
+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.

Can you add more detail on why the sum can exceed 100%?

Review

Quoted 2 lines
(quoted diff) +2 -0
+
+Let me see you an example; there’re three functions like below.

That sentence needs some work and should stay in 3rd person. Maybe something like this:

"Consider the following example:"

Quoted 35 lines
tools/perf/Documentation/overhead.txt new file +35 -0
+
+-----------------------
+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
+

tools/perf/Documentation/overhead.txt line 63

Quoted 10 lines
tools/perf/Documentation/overhead.txt new file +10 -0
+  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:

Man pages should avoid contractions, should be in 3rd person and s/somethink/something/.

"When --children option is enabled, the (self) overhead of children (in this case foo and bar) are added to the parent to calculate the children overhead. In this case the report could display as:"

Quoted 21 lines
tools/perf/Documentation/overhead.txt new file +21 -0
+
+-------------------------------------------
+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
+          |

tools/perf/Documentation/overhead.txt line 94

Quoted 10 lines
tools/perf/Documentation/overhead.txt new file +10 -0
+          --- 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.

Maintain tense. Something like:

"Since v3.16 the children overhead is shown by default and the output is sorted by the values. Children overhead is disabled by specifying --no-children option on the command line or by adding 'report.children = false' or 'top.children = false' in the perfconfig file.

Overall nicely done. Thanks for taking the time to write this up.

David

author maintainer
#2 lore raw

Hi David,

Thanks for fixing my English :)

Quoted 6 lines · David Ahern

tools/perf/Documentation/overhead.txt line 16

Quoted 3 lines · Namhyung Kim
tools/perf/Documentation/overhead.txt new file +3 -0
+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.

Can you add more detail on why the sum can exceed 100%?

OK. How about this?

"It might confusing that the sum of the all children overhead exceeds 100% since each of them is already an accumulation of (self) overhead of its children."

Quoted 8 lines

Review

Quoted 3 lines
(quoted diff) +2 -0
+
+Let me see you an example; there’re three functions like below.

That sentence needs some work and should stay in 3rd person. Maybe something like this:

"Consider the following example:"

OK.

Quoted 50 lines
Quoted 36 lines
tools/perf/Documentation/overhead.txt new file +35 -0
+
+-----------------------
+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
+

tools/perf/Documentation/overhead.txt line 63

Quoted 10 lines
tools/perf/Documentation/overhead.txt new file +10 -0
+  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:

Man pages should avoid contractions, should be in 3rd person and s/somethink/something/.

Quoted 3 lines

"When --children option is enabled, the (self) overhead of children (in this case foo and bar) are added to the parent to calculate the children overhead. In this case the report could display as:"

OK.

Quoted 35 lines
Quoted 22 lines
tools/perf/Documentation/overhead.txt new file +21 -0
+
+-------------------------------------------
+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
+          |

tools/perf/Documentation/overhead.txt line 94

Quoted 10 lines
tools/perf/Documentation/overhead.txt new file +10 -0
+          --- 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.

Maintain tense. Something like:

Quoted 4 lines

"Since v3.16 the children overhead is shown by default and the output is sorted by the values. Children overhead is disabled by specifying --no-children option on the command line or by adding 'report.children = false' or 'top.children = false' in the perfconfig file.

OK

Quoted 2 lines

Overall nicely done. Thanks for taking the time to write this up.

And thank you so much for reviewing this! :)
Namhyung