[RFC/PATCH v2] perf report: Show random usage tip on the help line

[RFC/PATCH v2] perf report: Show random usage tip on the help line

[Namhyung Kim]

Currently perf report only shows a help message "For a higher level
overview, try: perf report --sort comm,dso" unconditionally (even if
the sort keys were used).  Add more help tips and show randomly.

Load tips from ${prefix}/share/doc/perf-tip/tips.txt file.

  $ perf report | tail
      0.10%  swapper  [kernel.vmlinux]   [k] irq_exit
      0.09%  swapper  [kernel.vmlinux]   [k] flush_smp_call_function_queue
      0.08%  swapper  [kernel.vmlinux]   [k] native_write_msr_safe
      0.03%  swapper  [kernel.vmlinux]   [k] group_sched_in
      0.01%  perf     [kernel.vmlinux]   [k] native_write_msr_safe

  #
  # (Tip: Search options using a keyword: perf report -h filter)
  #

Signed-off-by: Namhyung Kim <namhyung@kernel.org>
---
More tips will be added later once this basic structure is done.

 tools/perf/Build                  |  1 +
 tools/perf/Documentation/tips.txt | 14 ++++++++++++++
 tools/perf/Makefile.perf          |  3 +++
 tools/perf/builtin-report.c       |  2 +-
 tools/perf/config/Makefile        |  6 ++++++
 tools/perf/perf.c                 |  4 ++++
 tools/perf/util/util.c            | 27 +++++++++++++++++++++++++++
 tools/perf/util/util.h            |  2 ++
 8 files changed, 58 insertions(+), 1 deletion(-)
 create mode 100644 tools/perf/Documentation/tips.txt

diff --git a/tools/perf/Build b/tools/perf/Build
index 00c4b8c3d8ca..6b67e6f4179f 100644
--- a/tools/perf/Build
+++ b/tools/perf/Build
@@ -41,6 +41,7 @@ CFLAGS_perf.o              += -DPERF_HTML_PATH="BUILD_STR($(htmldir_SQ))"	\
 			      -DPREFIX="BUILD_STR($(prefix_SQ))"		\
 			      -include $(OUTPUT)PERF-VERSION-FILE
 CFLAGS_builtin-trace.o	   += -DSTRACE_GROUPS_DIR="BUILD_STR($(STRACE_GROUPS_DIR_SQ))"
+CFLAGS_builtin-report.o	   += -DTIPDIR="BUILD_STR($(tipdir_SQ))"
 
 libperf-y += util/
 libperf-y += arch/
diff --git a/tools/perf/Documentation/tips.txt b/tools/perf/Documentation/tips.txt
new file mode 100644
index 000000000000..383aef8f9509
--- /dev/null
+++ b/tools/perf/Documentation/tips.txt
@@ -0,0 +1,14 @@
+For a higher level overview, try: perf report --sort comm,dso
+Group related events with: perf record -e '{cycles,instructions}:S'
+Compare performance results with: perf diff [<old file> <new file>]
+Boolean options have negative forms like: perf report --no-children
+Customize output of perf script with: perf script -F event,ip,sym
+Generate a script for your data: perf script -g <lang>
+Save output of perf stat using: perf stat record
+Create archive of data to see it on other machine: perf archive
+Search options using a keyword: perf report -h <keyword>
+Use parent filter to see specific call path: perf report -p <regex>
+listing interested events using substring match: perf list <keyword>
+To see list of saved events and attributes: perf evlist -v
+Use --symfs <dir> if your symbol files are in non-standard location
+To see callchains in a more compact form: perf report -g folded
diff --git a/tools/perf/Makefile.perf b/tools/perf/Makefile.perf
index 404e3b1c4e31..b6ee9c1982ec 100644
--- a/tools/perf/Makefile.perf
+++ b/tools/perf/Makefile.perf
@@ -567,6 +567,9 @@ endif
 	$(call QUIET_INSTALL, perf_completion-script) \
 		$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(sysconfdir_SQ)/bash_completion.d'; \
 		$(INSTALL) perf-completion.sh '$(DESTDIR_SQ)$(sysconfdir_SQ)/bash_completion.d/perf'
+	$(call QUIET_INSTALL, perf-tip) \
+		$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(tipdir_SQ)'; \
+		$(INSTALL) Documentation/tips.txt -t '$(DESTDIR_SQ)$(tipdir_SQ)'
 
 install-tests: all install-gtk
 	$(call QUIET_INSTALL, tests) \
diff --git a/tools/perf/builtin-report.c b/tools/perf/builtin-report.c
index f10c663af996..965143c98265 100644
--- a/tools/perf/builtin-report.c
+++ b/tools/perf/builtin-report.c
@@ -433,7 +433,7 @@ static int report__browse_hists(struct report *rep)
 	int ret;
 	struct perf_session *session = rep->session;
 	struct perf_evlist *evlist = session->evlist;
-	const char *help = "For a higher level overview, try: perf report --sort comm,dso";
+	const char *help = perf_report_tip(TIPDIR);
 
 	switch (use_browser) {
 	case 1:
diff --git a/tools/perf/config/Makefile b/tools/perf/config/Makefile
index 18b2f96d0941..254d06e39bea 100644
--- a/tools/perf/config/Makefile
+++ b/tools/perf/config/Makefile
@@ -691,6 +691,7 @@ sharedir = $(prefix)/share
 template_dir = share/perf-core/templates
 STRACE_GROUPS_DIR = share/perf-core/strace/groups
 htmldir = share/doc/perf-doc
+tipdir = share/doc/perf-tip
 ifeq ($(prefix),/usr)
 sysconfdir = /etc
 ETC_PERFCONFIG = $(sysconfdir)/perfconfig
@@ -717,6 +718,7 @@ infodir_SQ = $(subst ','\'',$(infodir))
 perfexecdir_SQ = $(subst ','\'',$(perfexecdir))
 template_dir_SQ = $(subst ','\'',$(template_dir))
 htmldir_SQ = $(subst ','\'',$(htmldir))
+tipdir_SQ = $(subst ','\'',$(tipdir))
 prefix_SQ = $(subst ','\'',$(prefix))
 sysconfdir_SQ = $(subst ','\'',$(sysconfdir))
 libdir_SQ = $(subst ','\'',$(libdir))
@@ -724,12 +726,15 @@ libdir_SQ = $(subst ','\'',$(libdir))
 ifneq ($(filter /%,$(firstword $(perfexecdir))),)
 perfexec_instdir = $(perfexecdir)
 STRACE_GROUPS_INSTDIR = $(STRACE_GROUPS_DIR)
+tip_instdir = $(tipdir)
 else
 perfexec_instdir = $(prefix)/$(perfexecdir)
 STRACE_GROUPS_INSTDIR = $(prefix)/$(STRACE_GROUPS_DIR)
+tip_instdir = $(prefix)/$(tipdir)
 endif
 perfexec_instdir_SQ = $(subst ','\'',$(perfexec_instdir))
 STRACE_GROUPS_INSTDIR_SQ = $(subst ','\'',$(STRACE_GROUPS_INSTDIR))
+tip_instdir_SQ = $(subst ','\'',$(tip_instdir))
 
 # If we install to $(HOME) we keep the traceevent default:
 # $(HOME)/.traceevent/plugins
@@ -770,6 +775,7 @@ $(call detected_var,ETC_PERFCONFIG_SQ)
 $(call detected_var,STRACE_GROUPS_DIR_SQ)
 $(call detected_var,prefix_SQ)
 $(call detected_var,perfexecdir_SQ)
+$(call detected_var,tipdir_SQ)
 $(call detected_var,LIBDIR)
 $(call detected_var,GTK_CFLAGS)
 $(call detected_var,PERL_EMBED_CCOPTS)
diff --git a/tools/perf/perf.c b/tools/perf/perf.c
index cb1d2499c45c..a929618b8eb6 100644
--- a/tools/perf/perf.c
+++ b/tools/perf/perf.c
@@ -19,6 +19,8 @@
 #include "util/debug.h"
 #include <api/fs/tracing_path.h>
 #include <pthread.h>
+#include <stdlib.h>
+#include <time.h>
 
 const char perf_usage_string[] =
 	"perf [--version] [--help] [OPTIONS] COMMAND [ARGS]";
@@ -542,6 +544,8 @@ int main(int argc, const char **argv)
 	if (!cmd)
 		cmd = "perf-help";
 
+	srandom(time(NULL));
+
 	/* get debugfs/tracefs mount point from /proc/mounts */
 	tracing_path_mount();
 
diff --git a/tools/perf/util/util.c b/tools/perf/util/util.c
index aff0cfd83662..f3a50bad756c 100644
--- a/tools/perf/util/util.c
+++ b/tools/perf/util/util.c
@@ -16,6 +16,8 @@
 #include <linux/kernel.h>
 #include <unistd.h>
 #include "callchain.h"
+#include "strlist.h"
+#include <subcmd/exec-cmd.h>
 
 struct callchain_param	callchain_param = {
 	.mode	= CHAIN_GRAPH_ABS,
@@ -663,3 +665,28 @@ fetch_kernel_version(unsigned int *puint, char *str,
 		*puint = (version << 16) + (patchlevel << 8) + sublevel;
 	return 0;
 }
+
+const char *perf_report_tip(const char *dirname)
+{
+	struct strlist *tips;
+	struct str_node *node;
+	char *tip = NULL;
+	struct strlist_config conf = {
+		.dirname = system_path(dirname) ,
+	};
+
+	tips = strlist__new("tips.txt", &conf);
+	if (tips == NULL || strlist__nr_entries(tips) == 1) {
+		tip = (char *)"Cannot find tips.txt file";
+		goto out;
+	}
+
+	node = strlist__entry(tips, random() % strlist__nr_entries(tips));
+	if (asprintf(&tip, "Tip: %s", node->s) < 0)
+		tip = (char *)"Not enough memory";
+
+out:
+	strlist__delete(tips);
+
+	return tip;
+}
diff --git a/tools/perf/util/util.h b/tools/perf/util/util.h
index 4b519c59bdc3..d8fc48e76139 100644
--- a/tools/perf/util/util.h
+++ b/tools/perf/util/util.h
@@ -342,4 +342,6 @@ int fetch_kernel_version(unsigned int *puint,
 #define KVER_FMT	"%d.%d.%d"
 #define KVER_PARAM(x)	KVER_VERSION(x), KVER_PATCHLEVEL(x), KVER_SUBLEVEL(x)
 
+const char *perf_report_tip(const char *dirname);
+
 #endif /* GIT_COMPAT_UTIL_H */
-- 
2.6.4

Re: [RFC/PATCH v2] perf report: Show random usage tip on the help line

[Jiri Olsa]

On Thu, Jan 07, 2016 at 04:46:22PM +0900, Namhyung Kim wrote:

SNIP

> +const char *perf_report_tip(const char *dirname)
> +{
> +	struct strlist *tips;
> +	struct str_node *node;
> +	char *tip = NULL;
> +	struct strlist_config conf = {
> +		.dirname = system_path(dirname) ,
> +	};
> +
> +	tips = strlist__new("tips.txt", &conf);
> +	if (tips == NULL || strlist__nr_entries(tips) == 1) {
> +		tip = (char *)"Cannot find tips.txt file";
> +		goto out;
> +	}
> +
> +	node = strlist__entry(tips, random() % strlist__nr_entries(tips));
> +	if (asprintf(&tip, "Tip: %s", node->s) < 0)
> +		tip = (char *)"Not enough memory";

                ^^^ this could be tip = (char *) "Tip: get more memory!";  ;-)

jirka

Re: [RFC/PATCH v2] perf report: Show random usage tip on the help line

[Jiri Olsa]

On Thu, Jan 07, 2016 at 04:46:22PM +0900, Namhyung Kim wrote:

SNIP

>  
>  struct callchain_param	callchain_param = {
>  	.mode	= CHAIN_GRAPH_ABS,
> @@ -663,3 +665,28 @@ fetch_kernel_version(unsigned int *puint, char *str,
>  		*puint = (version << 16) + (patchlevel << 8) + sublevel;
>  	return 0;
>  }
> +
> +const char *perf_report_tip(const char *dirname)
> +{
> +	struct strlist *tips;
> +	struct str_node *node;
> +	char *tip = NULL;
> +	struct strlist_config conf = {
> +		.dirname = system_path(dirname) ,
> +	};
> +
> +	tips = strlist__new("tips.txt", &conf);
> +	if (tips == NULL || strlist__nr_entries(tips) == 1) {
> +		tip = (char *)"Cannot find tips.txt file";
> +		goto out;

could we also try to read "./Documentation/tips.txt" ?

so people who don't install perf and run it from 'tools/perf'
get some tips as well? ;-)

[jolsa@krava perf]$ ./perf report --stdio  | tail -3
#
# (Cannot find tips.txt file)
#
[jolsa@krava perf]$ 

thanks,
jirka

Re: [RFC/PATCH v2] perf report: Show random usage tip on the help line

[Jiri Olsa]

On Thu, Jan 07, 2016 at 09:07:17AM +0100, Jiri Olsa wrote:
> On Thu, Jan 07, 2016 at 04:46:22PM +0900, Namhyung Kim wrote:
> 
> SNIP
> 
> >  
> >  struct callchain_param	callchain_param = {
> >  	.mode	= CHAIN_GRAPH_ABS,
> > @@ -663,3 +665,28 @@ fetch_kernel_version(unsigned int *puint, char *str,
> >  		*puint = (version << 16) + (patchlevel << 8) + sublevel;
> >  	return 0;
> >  }
> > +
> > +const char *perf_report_tip(const char *dirname)
> > +{
> > +	struct strlist *tips;
> > +	struct str_node *node;
> > +	char *tip = NULL;
> > +	struct strlist_config conf = {
> > +		.dirname = system_path(dirname) ,
> > +	};
> > +
> > +	tips = strlist__new("tips.txt", &conf);
> > +	if (tips == NULL || strlist__nr_entries(tips) == 1) {
> > +		tip = (char *)"Cannot find tips.txt file";
> > +		goto out;
> 
> could we also try to read "./Documentation/tips.txt" ?
> 
> so people who don't install perf and run it from 'tools/perf'
> get some tips as well? ;-)
> 
> [jolsa@krava perf]$ ./perf report --stdio  | tail -3
> #
> # (Cannot find tips.txt file)
> #
> [jolsa@krava perf]$ 

also some people use local user install and it seems
not to be installed under this one as well


[jolsa@krava perf]$ make install
  BUILD:   Doing 'make -j4' parallel build
  SUBDIR   Documentation
  INSTALL  Documentation-man
  INSTALL  trace_plugins
  INSTALL  GTK UI
  INSTALL  binaries
  INSTALL  tests
  INSTALL  perf-read-vdso32
  INSTALL  libexec
  INSTALL  perf-archive
  INSTALL  perf-with-kcore
  INSTALL  strace/groups
  INSTALL  perl-scripts
  INSTALL  python-scripts
  INSTALL  perf_completion-script
  INSTALL  perf-tip
[jolsa@krava perf]$ ./perf report --stdio  | tail -3
#
# (Cannot find tips.txt file)
#

thanks,
jirka

Re: [RFC/PATCH v2] perf report: Show random usage tip on the help line

[Namhyung Kim]

On Thu, Jan 07, 2016 at 09:07:17AM +0100, Jiri Olsa wrote:
> On Thu, Jan 07, 2016 at 04:46:22PM +0900, Namhyung Kim wrote:
> 
> SNIP
> 
> >  
> >  struct callchain_param	callchain_param = {
> >  	.mode	= CHAIN_GRAPH_ABS,
> > @@ -663,3 +665,28 @@ fetch_kernel_version(unsigned int *puint, char *str,
> >  		*puint = (version << 16) + (patchlevel << 8) + sublevel;
> >  	return 0;
> >  }
> > +
> > +const char *perf_report_tip(const char *dirname)
> > +{
> > +	struct strlist *tips;
> > +	struct str_node *node;
> > +	char *tip = NULL;
> > +	struct strlist_config conf = {
> > +		.dirname = system_path(dirname) ,
> > +	};
> > +
> > +	tips = strlist__new("tips.txt", &conf);
> > +	if (tips == NULL || strlist__nr_entries(tips) == 1) {
> > +		tip = (char *)"Cannot find tips.txt file";
> > +		goto out;
> 
> could we also try to read "./Documentation/tips.txt" ?
> 
> so people who don't install perf and run it from 'tools/perf'
> get some tips as well? ;-)

I thought about that too.  But using relative path is not a good idea
IMHO since there's no guarantee we're in the perf source directory.
Maybe we can path $srcdir or so, but given that only *very* few people
like you will need it, I'd rather not doing that. :)

Thanks,
Namhyung


> 
> [jolsa@krava perf]$ ./perf report --stdio  | tail -3
> #
> # (Cannot find tips.txt file)
> #
> [jolsa@krava perf]$ 
> 
> thanks,
> jirka

Re: [RFC/PATCH v2] perf report: Show random usage tip on the help line

[Namhyung Kim]

On Thu, Jan 07, 2016 at 09:09:59AM +0100, Jiri Olsa wrote:
> On Thu, Jan 07, 2016 at 09:07:17AM +0100, Jiri Olsa wrote:
> > On Thu, Jan 07, 2016 at 04:46:22PM +0900, Namhyung Kim wrote:
> > 
> > SNIP
> > 
> > >  
> > >  struct callchain_param	callchain_param = {
> > >  	.mode	= CHAIN_GRAPH_ABS,
> > > @@ -663,3 +665,28 @@ fetch_kernel_version(unsigned int *puint, char *str,
> > >  		*puint = (version << 16) + (patchlevel << 8) + sublevel;
> > >  	return 0;
> > >  }
> > > +
> > > +const char *perf_report_tip(const char *dirname)
> > > +{
> > > +	struct strlist *tips;
> > > +	struct str_node *node;
> > > +	char *tip = NULL;
> > > +	struct strlist_config conf = {
> > > +		.dirname = system_path(dirname) ,
> > > +	};
> > > +
> > > +	tips = strlist__new("tips.txt", &conf);
> > > +	if (tips == NULL || strlist__nr_entries(tips) == 1) {
> > > +		tip = (char *)"Cannot find tips.txt file";
> > > +		goto out;
> > 
> > could we also try to read "./Documentation/tips.txt" ?
> > 
> > so people who don't install perf and run it from 'tools/perf'
> > get some tips as well? ;-)
> > 
> > [jolsa@krava perf]$ ./perf report --stdio  | tail -3
> > #
> > # (Cannot find tips.txt file)
> > #
> > [jolsa@krava perf]$ 
> 
> also some people use local user install and it seems
> not to be installed under this one as well
> 
> 
> [jolsa@krava perf]$ make install
>   BUILD:   Doing 'make -j4' parallel build
>   SUBDIR   Documentation
>   INSTALL  Documentation-man
>   INSTALL  trace_plugins
>   INSTALL  GTK UI
>   INSTALL  binaries
>   INSTALL  tests
>   INSTALL  perf-read-vdso32
>   INSTALL  libexec
>   INSTALL  perf-archive
>   INSTALL  perf-with-kcore
>   INSTALL  strace/groups
>   INSTALL  perl-scripts
>   INSTALL  python-scripts
>   INSTALL  perf_completion-script
>   INSTALL  perf-tip
> [jolsa@krava perf]$ ./perf report --stdio  | tail -3
> #
> # (Cannot find tips.txt file)
> #

Oops, I should use tip_instdir_SQ instead of tipdir_SQ when
installing.  Will send the fix soon.

Thanks,
Namhyung

Re: [RFC/PATCH v2] perf report: Show random usage tip on the help line

[Namhyung Kim]

On Thu, Jan 07, 2016 at 09:03:20AM +0100, Jiri Olsa wrote:
> On Thu, Jan 07, 2016 at 04:46:22PM +0900, Namhyung Kim wrote:
> 
> SNIP
> 
> > +const char *perf_report_tip(const char *dirname)
> > +{
> > +	struct strlist *tips;
> > +	struct str_node *node;
> > +	char *tip = NULL;
> > +	struct strlist_config conf = {
> > +		.dirname = system_path(dirname) ,
> > +	};
> > +
> > +	tips = strlist__new("tips.txt", &conf);
> > +	if (tips == NULL || strlist__nr_entries(tips) == 1) {
> > +		tip = (char *)"Cannot find tips.txt file";
> > +		goto out;
> > +	}
> > +
> > +	node = strlist__entry(tips, random() % strlist__nr_entries(tips));
> > +	if (asprintf(&tip, "Tip: %s", node->s) < 0)
> > +		tip = (char *)"Not enough memory";
> 
>                 ^^^ this could be tip = (char *) "Tip: get more memory!";  ;-)

Haha.  Will change. :)

Thanks,
Namhyung

Re: [RFC/PATCH v2] perf report: Show random usage tip on the help line

[Andi Kleen]

On Thu, Jan 07, 2016 at 04:46:22PM +0900, Namhyung Kim wrote:
> Currently perf report only shows a help message "For a higher level
> overview, try: perf report --sort comm,dso" unconditionally (even if
> the sort keys were used).  Add more help tips and show randomly.
> 
> Load tips from ${prefix}/share/doc/perf-tip/tips.txt file.

It would be better to compile them in in at build time from
the documentation file.

Often perf is not installed, and if people don't install they
never see the tips.

> @@ -0,0 +1,14 @@
> +For a higher level overview, try: perf report --sort comm,dso
> +Group related events with: perf record -e '{cycles,instructions}:S'
> +Compare performance results with: perf diff [<old file> <new file>]
> +Boolean options have negative forms like: perf report --no-children
> +Customize output of perf script with: perf script -F event,ip,sym
> +Generate a script for your data: perf script -g <lang>
> +Save output of perf stat using: perf stat record
> +Create archive of data to see it on other machine: perf archive
> +Search options using a keyword: perf report -h <keyword>
> +Use parent filter to see specific call path: perf report -p <regex>
> +listing interested events using substring match: perf list <keyword>
> +To see list of saved events and attributes: perf evlist -v
> +Use --symfs <dir> if your symbol files are in non-standard location
> +To see callchains in a more compact form: perf report -g folded

What happened to my tips?

-Andi

Re: [RFC/PATCH v2] perf report: Show random usage tip on the help line

[Jiri Olsa]

On Thu, Jan 07, 2016 at 05:47:53PM +0100, Andi Kleen wrote:
> On Thu, Jan 07, 2016 at 04:46:22PM +0900, Namhyung Kim wrote:
> > Currently perf report only shows a help message "For a higher level
> > overview, try: perf report --sort comm,dso" unconditionally (even if
> > the sort keys were used).  Add more help tips and show randomly.
> > 
> > Load tips from ${prefix}/share/doc/perf-tip/tips.txt file.
> 
> It would be better to compile them in in at build time from
> the documentation file.
> 
> Often perf is not installed, and if people don't install they
> never see the tips.

+1 ;-)

jirka