[PATCH] perf stat: Add --hide-zero-events option to suppress zero-count events

[PATCH] perf stat: Add --hide-zero-events option to suppress zero-count events

[Aaron Tomlin]

When monitoring a large number of events (e.g., with wildcards such as
--event 'syscalls:sys_enter_*'), many matched events will return a count
of zero. This clutters the output, making it difficult to spot the
active events.

Add a new option --hide-zero-events to suppress printing events that
have a count of zero.

To prevent formatting and diagnostic issues, the zero-skipping logic
implements the following rules:

    1. In metric-only mode (i.e., --metric-only), columns must remain
       aligned in the output grid. We evaluate config->metric_only first
       to avoid skipping zero-valued columns, preventing values from
       shifting left and aligning under incorrect headers

    2. For explicitly requested events, we ensure they are not silently
       hidden if they are unsupported. We only hide a zero-count event
       if counter->supported is true, ensuring that unsupported explicit
       events still report "<not supported>"

Signed-off-by: Aaron Tomlin <atomlin@atomlin.com>
---
 tools/perf/Documentation/perf-stat.txt | 3 +++
 tools/perf/builtin-stat.c              | 2 ++
 tools/perf/util/stat-display.c         | 3 +++
 tools/perf/util/stat.h                 | 1 +
 4 files changed, 9 insertions(+)

diff --git a/tools/perf/Documentation/perf-stat.txt b/tools/perf/Documentation/perf-stat.txt
index b72a29c9223c..f334aabdc809 100644
--- a/tools/perf/Documentation/perf-stat.txt
+++ b/tools/perf/Documentation/perf-stat.txt
@@ -162,6 +162,9 @@ null run - Don't start any counters.
 This can be useful to measure just elapsed wall-clock time - or to assess the
 raw overhead of perf stat itself, without running any counters.
 
+--hide-zero-events::
+Do not show events with a zero count.
+
 -v::
 --verbose::
         be more verbose (show counter open errors, etc)
diff --git a/tools/perf/builtin-stat.c b/tools/perf/builtin-stat.c
index a04466ea3b0a..8d340c2ae76c 100644
--- a/tools/perf/builtin-stat.c
+++ b/tools/perf/builtin-stat.c
@@ -2493,6 +2493,8 @@ int cmd_stat(int argc, const char **argv)
 			"display details about each run (only with -r option)"),
 		OPT_BOOLEAN('n', "null", &stat_config.null_run,
 			"null run - dont start any counters"),
+		OPT_BOOLEAN(0, "hide-zero-events", &stat_config.hide_zero,
+			"Do not show events with a zero count"),
 		OPT_INCR('d', "detailed", &detailed_run,
 			"detailed run - start a lot of events"),
 		OPT_BOOLEAN('S', "sync", &sync_run,
diff --git a/tools/perf/util/stat-display.c b/tools/perf/util/stat-display.c
index 0a5750bb59fa..1579e3e2c445 100644
--- a/tools/perf/util/stat-display.c
+++ b/tools/perf/util/stat-display.c
@@ -907,6 +907,9 @@ static bool should_skip_zero_counter(struct perf_stat_config *config,
 	/* Metric only counts won't be displayed but the metric wants to be computed. */
 	if (config->metric_only)
 		return false;
+
+	if (config->hide_zero && counter->supported)
+		return true;
 	/*
 	 * Skip value 0 when enabling --per-thread globally,
 	 * otherwise it will have too many 0 output.
diff --git a/tools/perf/util/stat.h b/tools/perf/util/stat.h
index 4bced233d2fc..e3598037a6aa 100644
--- a/tools/perf/util/stat.h
+++ b/tools/perf/util/stat.h
@@ -69,6 +69,7 @@ struct perf_stat_config {
 	bool			 interval_clear;
 	bool			 metric_only;
 	bool			 null_run;
+	bool			 hide_zero;
 	bool			 ru_display;
 	bool			 big_num;
 	bool			 hybrid_merge;
-- 
2.54.0

Re: [PATCH] perf stat: Add --hide-zero-events option to suppress zero-count events

[Ian Rogers]

On Thu, Jul 16, 2026 at 7:31 PM Aaron Tomlin <atomlin@atomlin.com> wrote:
>
> When monitoring a large number of events (e.g., with wildcards such as
> --event 'syscalls:sys_enter_*'), many matched events will return a count
> of zero. This clutters the output, making it difficult to spot the
> active events.
>
> Add a new option --hide-zero-events to suppress printing events that
> have a count of zero.
>
> To prevent formatting and diagnostic issues, the zero-skipping logic
> implements the following rules:
>
>     1. In metric-only mode (i.e., --metric-only), columns must remain
>        aligned in the output grid. We evaluate config->metric_only first
>        to avoid skipping zero-valued columns, preventing values from
>        shifting left and aligning under incorrect headers
>
>     2. For explicitly requested events, we ensure they are not silently
>        hidden if they are unsupported. We only hide a zero-count event
>        if counter->supported is true, ensuring that unsupported explicit
>        events still report "<not supported>"
>
> Signed-off-by: Aaron Tomlin <atomlin@atomlin.com>

I think this makes sense but perhaps the Python interface makes more
sense for what you're doing. For example, the ilist app shows all
events and metrics:
https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/tree/tools/perf/python/ilist.py?h=perf-tools-next

Perhaps we could also add some tests for better coverage:
https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/tree/tools/perf/tests/shell/stat.sh?h=perf-tools-next

Other than that:
Reviewed-by: Ian Rogers <irogers@google.com>

Thanks,
Ian

> ---
>  tools/perf/Documentation/perf-stat.txt | 3 +++
>  tools/perf/builtin-stat.c              | 2 ++
>  tools/perf/util/stat-display.c         | 3 +++
>  tools/perf/util/stat.h                 | 1 +
>  4 files changed, 9 insertions(+)
>
> diff --git a/tools/perf/Documentation/perf-stat.txt b/tools/perf/Documentation/perf-stat.txt
> index b72a29c9223c..f334aabdc809 100644
> --- a/tools/perf/Documentation/perf-stat.txt
> +++ b/tools/perf/Documentation/perf-stat.txt
> @@ -162,6 +162,9 @@ null run - Don't start any counters.
>  This can be useful to measure just elapsed wall-clock time - or to assess the
>  raw overhead of perf stat itself, without running any counters.
>
> +--hide-zero-events::
> +Do not show events with a zero count.
> +
>  -v::
>  --verbose::
>          be more verbose (show counter open errors, etc)
> diff --git a/tools/perf/builtin-stat.c b/tools/perf/builtin-stat.c
> index a04466ea3b0a..8d340c2ae76c 100644
> --- a/tools/perf/builtin-stat.c
> +++ b/tools/perf/builtin-stat.c
> @@ -2493,6 +2493,8 @@ int cmd_stat(int argc, const char **argv)
>                         "display details about each run (only with -r option)"),
>                 OPT_BOOLEAN('n', "null", &stat_config.null_run,
>                         "null run - dont start any counters"),
> +               OPT_BOOLEAN(0, "hide-zero-events", &stat_config.hide_zero,
> +                       "Do not show events with a zero count"),
>                 OPT_INCR('d', "detailed", &detailed_run,
>                         "detailed run - start a lot of events"),
>                 OPT_BOOLEAN('S', "sync", &sync_run,
> diff --git a/tools/perf/util/stat-display.c b/tools/perf/util/stat-display.c
> index 0a5750bb59fa..1579e3e2c445 100644
> --- a/tools/perf/util/stat-display.c
> +++ b/tools/perf/util/stat-display.c
> @@ -907,6 +907,9 @@ static bool should_skip_zero_counter(struct perf_stat_config *config,
>         /* Metric only counts won't be displayed but the metric wants to be computed. */
>         if (config->metric_only)
>                 return false;
> +
> +       if (config->hide_zero && counter->supported)
> +               return true;
>         /*
>          * Skip value 0 when enabling --per-thread globally,
>          * otherwise it will have too many 0 output.
> diff --git a/tools/perf/util/stat.h b/tools/perf/util/stat.h
> index 4bced233d2fc..e3598037a6aa 100644
> --- a/tools/perf/util/stat.h
> +++ b/tools/perf/util/stat.h
> @@ -69,6 +69,7 @@ struct perf_stat_config {
>         bool                     interval_clear;
>         bool                     metric_only;
>         bool                     null_run;
> +       bool                     hide_zero;
>         bool                     ru_display;
>         bool                     big_num;
>         bool                     hybrid_merge;
> --
> 2.54.0
>