perf tools: Document --children option in more detail
Namhyung Kim
maintainerPATCH v2 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 | 96 ++++++++++++++++++++++++++++++++ tools/perf/Documentation/perf-report.txt | 4 ++ tools/perf/Documentation/perf-top.txt | 3 +- 3 files changed, 102 insertions(+), 1 deletion(-) create mode 100644 tools/perf/Documentation/overhead.txt
tools/perf/Documentation/overhead.txt new file +96 -0
@@ -0,0 +1,96 @@ +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 be 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. But with this enabled, users can find which +function has the most overhead even if samples are spread over the +children. + +Consider the following 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) are added to the parent to calculate the +children overhead. In this case the report could be displayed 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 +------------------------------------------- + +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.
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
Quoted 3 lines · 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 ;-).
Nice! :-)
Quoted 1 line
+++
b/tools/perf/Documentation/overhead.txt
As some people might stumble upon this the old fashioned way, by looking around in 'Documentation/', I'm wondering how this file name will tell the reader that this is about call chains? (which isn't the default recording mode) Maybe name it more explicitly, like callchain-overhead.txt?
tools/perf/Documentation/overhead.txt line 7
Quoted 8 lines
tools/perf/Documentation/overhead.txt new file +7
-0@@ -0,0 +1,96 @@ +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%.
s/sum of the all self overhead should be 100%
/sum of all the self-overhead values should be 100%
?
tools/perf/Documentation/overhead.txt line 12
Quoted 5 lines
tools/perf/Documentation/overhead.txt new file +5
-0+ +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.
Maybe put it into quotes to specify it more clearly? Also, maybe add a bit more info - Something like:
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 even if they don't directly execute much. 'Children' here means functions that are called from another (parent) function.
?
Review line 14
Quoted 2 lines
(quoted diff) +2
-0+ +It might be confusing that the sum of the all children overhead
s/children
/'children'
tools/perf/Documentation/overhead.txt line 27
Quoted 13 lines
tools/perf/Documentation/overhead.txt new file +13
-0+exceeds 100% since each of them is already an accumulation of (self) +overhead of its children. But with this enabled, users can find which +function has the most overhead even if samples are spread over the +children. + +Consider the following example; there’re three functions like below. + +----------------------- +void foo(void) { + /* something */ +} + +bar(void) {
s/bar(void) {
/void bar(void) {
:-)
tools/perf/Documentation/overhead.txt line 40
Quoted 13 lines
tools/perf/Documentation/overhead.txt new file +13
-0+ /* 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'.
s/and 'bar'. and
/and 'bar', and
Review line 42
Quoted 2 lines
(quoted diff) +2
-0+ +Suppose all samples are recorded in the 'foo' and 'bar' only. When
either:
Suppose all samples are recorded in the 'foo' and 'bar' functions only.
or:
Suppose all samples are recorded in 'foo' and 'bar' only.
tools/perf/Documentation/overhead.txt line 43
Quoted 1 line
tools/perf/Documentation/overhead.txt new file +1
-0+you record with callchain you'll see something like below in the usual
s/callchain/callchains
tools/perf/Documentation/overhead.txt line 44
Quoted 1 line
tools/perf/Documentation/overhead.txt new file +1
-0+(self-overhead-only) output of the perf report:
s/of the perf report/of perf report
Quoted 9 lines
tools/perf/Documentation/overhead.txt new file +9
-0+ +---------------------------------- +Overhead Symbol +........ ..................... + 60.00% foo + | + --- foo + bar + main
tools/perf/Documentation/overhead.txt line 63
Quoted 10 lines
tools/perf/Documentation/overhead.txt new file +10
-0+ __libc_start_main + + 40.00% bar + | + --- bar + main + __libc_start_main +---------------------------------- + +When --children option is enabled, the (self) overhead of children (in
s/When --children option
/When the --children option
Quoted 23 lines
tools/perf/Documentation/overhead.txt new file +23
-0+this case foo and bar) are added to the parent to calculate the +children overhead. In this case the report could be displayed 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 + |
tools/perf/Documentation/overhead.txt line 96
Quoted 10 lines
tools/perf/Documentation/overhead.txt new file +10
-0+ --- foo + bar + main + __libc_start_main +------------------------------------------- + +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.
s/perfconfig/.perfconfig
?
tools/perf/Documentation/perf-report.txt OPTIONS · line 196
Quoted 9 lines
tools/perf/Documentation/perf-report.txt +1
-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.
s/See `overhead calculation' section
/See the `overhead calculation' section
Quoted 18 lines
tools/perf/Documentation/perf-report.txt +3
-0--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 +0
-0
tools/perf/Documentation/perf-top.txt Default is to monitor all CPUS. · line 171
Quoted 5 lines
tools/perf/Documentation/perf-top.txt +1
-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.
s/See `overhead calculation' section
/See the `overhead calculation' section
With the above things fixed:
Thanks,
Ingo
Namhyung Kim
maintainerHi Ingo,
Quoted 8 lines · Ingo Molnar
Quoted 3 lines · 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 ;-).
Nice! :-)
Thanks! :)
Quoted 8 lines
Quoted 2 lines
+++
b/tools/perf/Documentation/overhead.txtAs some people might stumble upon this the old fashioned way, by looking around in '
Documentation/', I'm wondering how this file name will tell the reader that this is about call chains? (which isn't the default recording mode) Maybe name it more explicitly, like callchain-overhead.txt?
OK. But I'd rather name it 'overhead-calculation.txt' to align with the section name. And 'callchain-overhead' makes me thinking about the overhead of processing callchains at record or report time.
Quoted 13 lines
tools/perf/Documentation/overhead.txt line 7
Quoted 9 lines
tools/perf/Documentation/overhead.txt new file +7
-0@@ -0,0 +1,96 @@ +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%.s/sum of the all self overhead should be 100%
/sum of all the self-overhead values should be 100%
Quoted 1 line
?
OK
Quoted 16 lines
tools/perf/Documentation/overhead.txt line 12
Quoted 6 lines
tools/perf/Documentation/overhead.txt new file +5
-0+ +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.Maybe put it into quotes to specify it more clearly? Also, maybe add a bit more info - Something like:
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 even if they don't directly execute much. 'Children' here means functions that are called from another (parent) function.
Quoted 7 lines
?
Review line 14
Quoted 2 lines
(quoted diff) +2
-0+ +It might be confusing that the sum of the all children overheads/children
/'children'
Right!
Quoted 18 lines
Quoted 4 lines
tools/perf/Documentation/overhead.txt new file +3
-0+exceeds 100% since each of them is already an accumulation of (self) +overhead of its children. But with this enabled, users can find which +function has the most overhead even if samples are spread over thetools/perf/Documentation/overhead.txt line 27
Quoted 10 lines
tools/perf/Documentation/overhead.txt new file +10
-0+children. + +Consider the following example; there’re three functions like below. + +----------------------- +void foo(void) { + /* something */ +} + +bar(void) {s/bar(void) {
/void bar(void) {
Quoted 1 line
:-)
Oops..
Quoted 17 lines
Quoted 4 lines
tools/perf/Documentation/overhead.txt new file +3
-0+ /* do something */ + foo(); +}tools/perf/Documentation/overhead.txt line 40
Quoted 10 lines
tools/perf/Documentation/overhead.txt new file +10
-0+ +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'.s/and 'bar'. and
/and 'bar', and
OK
Quoted 9 lines
Review line 42
Quoted 3 lines
(quoted diff) +2
-0+ +Suppose all samples are recorded in the 'foo' and 'bar' only. Wheneither:
Suppose all samples are recorded in the 'foo' and 'bar' functions only.or:
Suppose all samples are recorded in 'foo' and 'bar' only.
I like the shorter. :)
Quoted 8 lines
tools/perf/Documentation/overhead.txt line 43
Quoted 2 lines
tools/perf/Documentation/overhead.txt new file +1
-0+you record with callchain you'll see something like below in the usuals/callchain/callchains
tools/perf/Documentation/overhead.txt line 44
Quoted 1 line
tools/perf/Documentation/overhead.txt new file +1
-0+(self-overhead-only) output of the perf report:s/of the perf report/of perf report
OK
Quoted 15 lines
Quoted 15 lines
tools/perf/Documentation/overhead.txt new file +14
-0+ +---------------------------------- +Overhead Symbol +........ ..................... + 60.00% foo + | + --- foo + bar + main + __libc_start_main + + 40.00% bar + | + --- bar
Quoted 8 lines
tools/perf/Documentation/overhead.txt line 63
Quoted 5 lines
tools/perf/Documentation/overhead.txt new file +5
-0+ main + __libc_start_main +---------------------------------- + +When --children option is enabled, the (self) overhead of children (ins/When --children option
/When the --children option
OK
Quoted 37 lines
Quoted 24 lines
tools/perf/Documentation/overhead.txt new file +23
-0+this case foo and bar) are added to the parent to calculate the +children overhead. In this case the report could be displayed 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 + |tools/perf/Documentation/overhead.txt line 96
Quoted 10 lines
tools/perf/Documentation/overhead.txt new file +10
-0+ --- foo + bar + main + __libc_start_main +------------------------------------------- + +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.s/perfconfig/.perfconfig
Quoted 1 line
?
It seems we can have a system-wide /etc/perfconfig too. How about 'the perf config file' instead?
Quoted 14 lines
tools/perf/Documentation/perf-report.txt OPTIONS · line 196
Quoted 11 lines
tools/perf/Documentation/perf-report.txt +1
-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.s/See `overhead calculation' section
/See the `overhead calculation' section
OK
Quoted 19 lines
Quoted 19 lines
tools/perf/Documentation/perf-report.txt +3
-0--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 +0
-0@@ -168,7 +168,7 @@ Default is to monitor all CPUS.
Quoted 8 lines
tools/perf/Documentation/perf-top.txt Default is to monitor all CPUS. · line 171
Quoted 5 lines
tools/perf/Documentation/perf-top.txt +1
-1Accumulate 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.s/See `overhead calculation' section
/See the `overhead calculation' section
OK
Quoted 2 lines
With the above things fixed:
Will fix all my bad English. :)
Quoted 2 lines
Reviewed-by Ingo Molnar <[email protected]>
Thanks for taking your time to review this!
Namhyung
Quoted 23 lines · Namhyung Kim
Hi Ingo,
Quoted 8 lines · Ingo Molnar
Quoted 3 lines · 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 ;-).
Nice! :-)
Thanks! :)
Quoted 8 lines
Quoted 2 lines
+++
b/tools/perf/Documentation/overhead.txtAs some people might stumble upon this the old fashioned way, by looking around in '
Documentation/', I'm wondering how this file name will tell the reader that this is about call chains? (which isn't the default recording mode) Maybe name it more explicitly, like callchain-overhead.txt?
Quoted 3 lines
OK. But I'd rather name it 'overhead-calculation.txt' to align with the section name. And 'callchain-overhead' makes me thinking about the overhead of processing callchains at record or report time.
Sure!
Quoted 6 lines
Quoted 3 lines
s/perfconfig/.perfconfig
?
It seems we can have a system-wide
/etc/perfconfigtoo. How about 'the perf config file' instead?
Yeah.
Thanks,
Ingo