Re: [PATCH v11 10/24] perf config: Document variables for 'call-graph' section in man page

[Namhyung Kim <namhyung@kernel.org>]

On Mon, Nov 30, 2015 at 10:42:00AM +0900, Taeung Song wrote:
> Hi, Namhyung

Hi Taeung,

> > On Nov 18, 2015, at 11:51 AM, Namhyung Kim <namhyung@kernel.org> wrote:
> > 
> > On Tue, Nov 17, 2015 at 10:53:30PM +0900, Taeung Song wrote:
> >> Explain 'call-graph' section and its variables.
> >> 
> >> 'record-mode', 'dump-size', 'print-type', 'order',
> >> 'sort-key', 'threshold' and 'print-limit'.
> >> 
> >> Cc: Namhyung Kim <namhyung@kernel.org>
> >> Cc: Jiri Olsa <jolsa@redhat.com>
> >> Signed-off-by: Taeung Song <treeze.taeung@gmail.com>
> >> ---
> >> tools/perf/Documentation/perf-config.txt | 65 ++++++++++++++++++++++++++++++++
> >> 1 file changed, 65 insertions(+)
> >> 
> >> diff --git a/tools/perf/Documentation/perf-config.txt b/tools/perf/Documentation/perf-config.txt
> >> index 7d386d4..dc659d6 100644
> >> --- a/tools/perf/Documentation/perf-config.txt
> >> +++ b/tools/perf/Documentation/perf-config.txt
> >> @@ -285,6 +285,71 @@ ui.*::
> >> 		There're columns as header 'Overhead', 'Children', 'Shared Object', 'Symbol', 'self'.
> >> 		If this option is false, they are hiden. This option is only applied to TUI.
> >> 
> >> +call-graph.*::
> >> +	When sub-commands 'top' and 'report' work with -g/—-children
> >> +	there're options in control of call-graph.
> >> +
> >> +	call-graph.record-mode::
> >> +		The record-mode can be 'fp' (frame pointer) and 'dwarf'.
> > 
> > Also 'lbr' can be used, but it only work for recent intel cpus.
> > 
> > 
> >> +		The value of 'dwarf' is effective only if perf detect needed library
> >> +		(libunwind or a recent version of libdw).  Also it doesn't *require*
> >> +		the dump-size option since it can use the default value of 8192 if
> >> +		missing.
> > 
> > I think the last sentence can be omitted.
> > 
> > 
> >> +
> >> +	call-graph.dump-size::
> >> +		The size of stack to dump in order to do post-unwinding. Default is 8192 (byte).
> >> +		When using dwarf into record-mode this option should have a value.
> > 
> > This contradicts the above, it'll use the default size if omitted.
> > 
> > 
> >> +
> >> +	call-graph.print-type::
> >> +		The print-types can be graph (graph absolute), fractal (graph relative), flat.

The 'folded' print type was added recently.  Please update it too.


> >> +		This option controls a way to show overhead for each callchain entry.
> >> +		Suppose a following example.
> >> +
> >> +		Overhead  Symbols
> >> +		........  .......
> >> +		  40.00%  foo
> >> +		      |
> >> +		      --- foo
> >> +		      |
> >> +		      |--50.00%-- bar
> >> +		      |           main
> >> +		      |
> >> +		      --50.00%-- baz
> >> +		                 main
> > 
> >                      ^
> > 		      it needs one more whitespace
> > 
> 
> I checked this patch file and whitespace and tab characters on it.
> But I think the lacking whitespace  because of mail client.
> After 'make install’ I checked it but there is no lack of whitespace.
> Are there different problems that I missed ?

I meant whitespace in the callchain graph (i.e. 'bar' and 'baz' should
be aligned).  But I think I was wrong - it should look like below:


  Overhead  Symbols
  ........  .......
    40.00%  foo
            |
            ---foo
               |
               |--50.00%--bar
               |          main
               |
                --50.00%--baz
                          main


Maybe it's because you used TAB characters for indent?

Thanks,
Namhyung


> 
> > 
> >> +
> >> +		This output is a 'fractal' format. The 'foo' came from 'bar' and 'baz' exactly
> >> +		half and half so 'fractal' shows 50.00% for each
> >> +		(meaning that it assumes 100% total overhead of 'foo').
> >> +
> >> +		The 'graph' uses absolute overhead value of 'foo' as total so each of
> >> +		'bar' and 'baz' callchain will have 20.00% of overhead.
> >> +
> >> +	call-graph.order::
> >> +		This option controls print order of callchains. The default is
> >> +		'callee' which means callee is printed at top and then followed by its
> >> +		caller and so on. The 'caller' prints it in reverse order.
> >> +
> >> +		If this option is not set and report.children or top.children is
> >> +		set to true (or the equivalent command line option is given),
> >> +		the default value of this option is changed to 'caller' for the
> >> +		execution of 'perf report' or 'perf top'. Other commands will
> >> +		still default to 'callee'.
> >> +
> >> +	call-graph.sort-key::
> >> +		The callchains are merged if they contain same information.
> >> +		The sort-key option determines a way to compare the callchains.
> >> +		A value of 'sort-key' can be 'function' or 'address'.
> >> +		The default is 'function'.
> >> +
> >> +	call-graph.threshold::
> >> +		When there're many callchains it'd print tons of lines.  So perf omits
> >> +		small callchains under a certain overhead (threshold) and this option
> >> +		control the threashold. Default is 0.5 (%).
> > 
> > s/threashold/threshold/
> > 
> > Also it'd be better to mention that the overhead is calculated by
> > value depends on call-graph.print-type.
> > 
> > 
> >> +
> >> +	call-graph.print-limit::
> >> +		This is another way to control the number of callchains printed for a
> >> +		single entry. Default is 0 which means no limitation.
> > 
> > This is a maximum number of lines of callchain printed for a single
> > histogram entry.
> > 
> > Thanks,
> > Namhyung
> > 
> > 
> >> +
> >> SEE ALSO
> >> --------
> >> linkperf:perf[1]
> >> -- 
> >> 1.9.1
>