[PATCH] perf tools: Document --children option in more detail

[PATCH] perf tools: Document --children option in more detail

[Namhyung Kim]

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

Re: [PATCH] perf tools: Document --children option in more detail

[David Ahern]

On 4/18/15 11:33 AM, Namhyung Kim wrote:
> +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%?

> +
> +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:"

> +
> +-----------------------
> +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:

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:"

> +
> +-------------------------------------------
> +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.

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

Re: [PATCH] perf tools: Document --children option in more detail

[Namhyung Kim]

Hi David,

Thanks for fixing my English :)

On Sun, Apr 19, 2015 at 11:11:14AM -0600, David Ahern wrote:
> On 4/18/15 11:33 AM, Namhyung Kim wrote:
> >+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."

> 
> >+
> >+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.

> 
> >+
> >+-----------------------
> >+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:
> 
> 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:"

OK.

> 
> >+
> >+-------------------------------------------
> >+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.
> 
> 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.

OK

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

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