perf tools: Document --children option in more detail
Namhyung Kim
maintainerPATCH 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
@@ -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
@@ -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
@@ -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
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
Namhyung Kim
maintainerHi 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