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

[RFC/PATCH v3] 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 <keyword>)
  #

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..964cf1201541 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)$(tip_instdir_SQ)'; \
+		$(INSTALL) Documentation/tips.txt -t '$(DESTDIR_SQ)$(tip_instdir_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..23ad4ba08aa4 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 *)"Tip: get more 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 v3] perf report: Show random usage tip on the help line

[Ingo Molnar]

* Namhyung Kim <namhyung@kernel.org> 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.

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

Very nice!

Acked-by: Ingo Molnar <mingo@kernel.org>

On top of this, what do you think about only doing a single tip per day, the 'tip 
of the day'? That would have two effects:

 - people who know all this already see this less

 - people who don't know all this will perhaps be more attentive, because a tip 
   for every report is more likely to get ignored.

This could be done via a flag in ~/.perf/ or so.

Another suggestion: shouldn't the tips be tool specific, i.e. shouldn't there be a 
tip-report.txt, tip-record.txt, etc. set of files?

Thanks,

	Ingo

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

[Ingo Molnar]

* Ingo Molnar <mingo@kernel.org> wrote:

> 
> * Namhyung Kim <namhyung@kernel.org> 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.
> 
> > +++ 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>

We could also include a more basic tip that suggests call graph recording? Most 
people don't know about it I think.

Thanks,

	Ingo

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

[Arnaldo Carvalho de Melo]

Em Fri, Jan 08, 2016 at 08:57:05AM +0100, Ingo Molnar escreveu:
> 
> * Namhyung Kim <namhyung@kernel.org> 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.
> 
> > +++ 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
> 
> Very nice!
> 
> Acked-by: Ingo Molnar <mingo@kernel.org>
> 
> On top of this, what do you think about only doing a single tip per day, the 'tip 
> of the day'? That would have two effects:
> 
>  - people who know all this already see this less
> 
>  - people who don't know all this will perhaps be more attentive, because a tip 
>    for every report is more likely to get ignored.
> 
> This could be done via a flag in ~/.perf/ or so.
> 
> Another suggestion: shouldn't the tips be tool specific, i.e. shouldn't there be a 
> tip-report.txt, tip-record.txt, etc. set of files?

Yeah, we could have per tool tip files, but then sometimes to use a
feature in 'report' we have to first use some magic combination on the
'record' command line.

Anyway, I think I'll apply Namhyung's latest, the one in this message,
and get the basic stuff in, we then go on improving on it.

- Arnaldo

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

[Namhyung Kim]

On Fri, Jan 08, 2016 at 08:57:05AM +0100, Ingo Molnar wrote:
> 
> * Namhyung Kim <namhyung@kernel.org> 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.
> 
> > +++ 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
> 
> Very nice!
> 
> Acked-by: Ingo Molnar <mingo@kernel.org>

Thanks!

> 
> On top of this, what do you think about only doing a single tip per day, the 'tip 
> of the day'? That would have two effects:
> 
>  - people who know all this already see this less
> 
>  - people who don't know all this will perhaps be more attentive, because a tip 
>    for every report is more likely to get ignored.
> 
> This could be done via a flag in ~/.perf/ or so.

Not sure.  Some people wanted to see more tips more frequently.

I think the 'tip of the day' might be good for regular users, but many
people just use perf when they need it and forget about it soon.  For
those people it'd be better to suggest useful tips more often.

Thanks,
Namhyung

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

[Namhyung Kim]

On Fri, Jan 08, 2016 at 09:54:41AM -0300, Arnaldo Carvalho de Melo wrote:
> Em Fri, Jan 08, 2016 at 08:57:05AM +0100, Ingo Molnar escreveu:
> > 
> > * Namhyung Kim <namhyung@kernel.org> 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.
> > 
> > > +++ 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
> > 
> > Very nice!
> > 
> > Acked-by: Ingo Molnar <mingo@kernel.org>
> > 
> > On top of this, what do you think about only doing a single tip per day, the 'tip 
> > of the day'? That would have two effects:
> > 
> >  - people who know all this already see this less
> > 
> >  - people who don't know all this will perhaps be more attentive, because a tip 
> >    for every report is more likely to get ignored.
> > 
> > This could be done via a flag in ~/.perf/ or so.
> > 
> > Another suggestion: shouldn't the tips be tool specific, i.e. shouldn't there be a 
> > tip-report.txt, tip-record.txt, etc. set of files?
> 
> Yeah, we could have per tool tip files, but then sometimes to use a
> feature in 'report' we have to first use some magic combination on the
> 'record' command line.

Right.  In addition, tips can depend on configurations, runtime
environment and so on.  But let's leave it as later work. :)


> 
> Anyway, I think I'll apply Namhyung's latest, the one in this message,
> and get the basic stuff in, we then go on improving on it.

Agreed!

Thanks,
Namhyung

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

[Namhyung Kim]

On Fri, Jan 08, 2016 at 09:06:35AM +0100, Ingo Molnar wrote:
> 
> * Ingo Molnar <mingo@kernel.org> wrote:
> 
> > 
> > * Namhyung Kim <namhyung@kernel.org> 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.
> > 
> > > +++ 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>
> 
> We could also include a more basic tip that suggests call graph recording? Most 
> people don't know about it I think.

Will add.

Thanks,
Namhyung

[tip:perf/core] perf report: Show random usage tip on the help line

[tip-bot for Namhyung Kim]

Commit-ID:  14cbfbeb76540cc0c53fbb0ba34b3a4900ebe40f
Gitweb:     http://git.kernel.org/tip/14cbfbeb76540cc0c53fbb0ba34b3a4900ebe40f
Author:     Namhyung Kim <namhyung@kernel.org>
AuthorDate: Thu, 7 Jan 2016 20:41:53 +0900
Committer:  Arnaldo Carvalho de Melo <acme@redhat.com>
CommitDate: Fri, 8 Jan 2016 13:15:46 -0300

perf report: Show random usage tip on the help line

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 <keyword>)
  #

Signed-off-by: Namhyung Kim <namhyung@kernel.org>
Acked-by: Ingo Molnar <mingo@kernel.org>
Cc: Andi Kleen <andi@firstfloor.org>
Cc: David Ahern <dsahern@gmail.com>
Cc: Jiri Olsa <jolsa@kernel.org>
Cc: Masami Hiramatsu <masami.hiramatsu.pt@hitachi.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Stephane Eranian <eranian@google.com>
Cc: Wang Nan <wangnan0@huawei.com>
Link: http://lkml.kernel.org/r/1452166913-27046-1-git-send-email-namhyung@kernel.org
[ Renamed it to perf_tip() and the parameter dirname to dirpath to fix the build on older distros ]
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>
---
 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(-)

diff --git a/tools/perf/Build b/tools/perf/Build
index 00c4b8c..6b67e6f 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 0000000..a1c10e3
--- /dev/null
+++ b/tools/perf/Documentation/tips.txt
@@ -0,0 +1,14 @@
+For a higher level overview, try: perf report --sort comm,dso
+Sample related events with: perf record -e '{cycles,instructions}:S'
+Compare performance results with: perf diff [<old file> <new file>]
+Boolean options have negative forms, e.g.: 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 <target workload>
+Create an archive with symtabs to analyse 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>
+List 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 locations
+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 1025ea7..0a22407 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)$(tip_instdir_SQ)'; \
+		$(INSTALL) Documentation/tips.txt -t '$(DESTDIR_SQ)$(tip_instdir_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 f10c663..d5a42ee 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_tip(TIPDIR);
 
 	switch (use_browser) {
 	case 1:
diff --git a/tools/perf/config/Makefile b/tools/perf/config/Makefile
index 18b2f96..254d06e 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 cb1d249..a929618 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 aff0cfd..88b8f8d 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_tip(const char *dirpath)
+{
+	struct strlist *tips;
+	struct str_node *node;
+	char *tip = NULL;
+	struct strlist_config conf = {
+		.dirname = system_path(dirpath) ,
+	};
+
+	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 *)"Tip: get more memory! ;-)";
+
+out:
+	strlist__delete(tips);
+
+	return tip;
+}
diff --git a/tools/perf/util/util.h b/tools/perf/util/util.h
index 4b519c5..fe915e6 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_tip(const char *dirpath);
+
 #endif /* GIT_COMPAT_UTIL_H */

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

[Ingo Molnar]

* Namhyung Kim <namhyung@kernel.org> wrote:

> > On top of this, what do you think about only doing a single tip per day, the 'tip 
> > of the day'? That would have two effects:
> > 
> >  - people who know all this already see this less
> > 
> >  - people who don't know all this will perhaps be more attentive, because a tip 
> >    for every report is more likely to get ignored.
> > 
> > This could be done via a flag in ~/.perf/ or so.
> 
> Not sure.  Some people wanted to see more tips more frequently.

Fair enough!

I now had some experience with the tips, and they are not intrusive.

> I think the 'tip of the day' might be good for regular users, but many people 
> just use perf when they need it and forget about it soon.  For those people it'd 
> be better to suggest useful tips more often.

Ok.

Thanks,

	Ingo