perf stat: worth documenting task-clock/cpu-clock in perf-stat.txt?

perf stat: worth documenting task-clock/cpu-clock in perf-stat.txt?

[Christian Melendez]

Hello Arnaldo,

I'm learning performance engineering and ran into this while playing
around with perf stat. perf-stat.txt's TIMINGS section explains "time
elapsed" and "user"/"sys", but I couldn't find task-clock itself
documented anywhere, even though it appears in the first command
example, as the very first metric shown.

This apparently came up unanswered on this list before, in 2013 and
2015 (2015: https://www.spinics.net/lists/linux-perf-users/msg02405.html),
where users asked about cpu-clock too, without anything ever being
added to the docs. Would it be worth documenting task-clock/cpu-clock
there? Happy to send a patch if so.

Best regards,
Christian

Re: perf stat: worth documenting task-clock/cpu-clock in perf-stat.txt?

[Ian Rogers]

On Tue, Sep 22, 2026 at 2:56 PM Christian Melendez <chrismelnu@gmail.com> wrote:
>
> Hello Arnaldo,
>
> I'm learning performance engineering and ran into this while playing
> around with perf stat. perf-stat.txt's TIMINGS section explains "time
> elapsed" and "user"/"sys", but I couldn't find task-clock itself
> documented anywhere, even though it appears in the first command
> example, as the very first metric shown.
>
> This apparently came up unanswered on this list before, in 2013 and
> 2015 (2015: https://www.spinics.net/lists/linux-perf-users/msg02405.html),
> where users asked about cpu-clock too, without anything ever being
> added to the docs. Would it be worth documenting task-clock/cpu-clock
> there? Happy to send a patch if so.

Extra documentation always sounds good to me. We added json
documentation for software events not long ago (it shows up in `perf
list`):
https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/tree/tools/perf/pmu-events/arch/common/common/software.json
There is also documentation of cpu-clock and task-clock in the
perf_event_open man page.

Thanks,
Ian

> Best regards,
> Christian
>

[PATCH] perf stat: document task-clock/cpu-clock in TIMINGS

[Christian Melendez]

task-clock/cpu-clock appear in perf stat's own example output but
were never explained in perf-stat.txt, unlike time elapsed/user/sys.
This came up unanswered on the list in 2013 and 2015 without docs
ever being added.

Link: https://patch.msgid.link/CAP-5=fV0-yvc68BUSKoSajHjHY_A6COgbEJYiFxRg+G-8LeJhQ@mail.gmail.com
Signed-off-by: Christian Melendez <chrismelnu@gmail.com>
---
 tools/perf/Documentation/perf-stat.txt | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/tools/perf/Documentation/perf-stat.txt b/tools/perf/Documentation/perf-stat.txt
index f334aabdc809..c0d6c344f9eb 100644
--- a/tools/perf/Documentation/perf-stat.txt
+++ b/tools/perf/Documentation/perf-stat.txt
@@ -621,6 +621,16 @@ user/system lands:
 
 Those times are the very same as displayed by the 'time' tool.
 
+We also display a clock-based timing metric that depends on the
+target being monitored:
+
+        83723.452481      task-clock:u (msec)       #    1.004 CPUs utilized
+
+For a single task, task-clock reports a clock count specific to that
+task. When the target is a CPU or the whole system (-a or -C),
+cpu-clock is reported instead. cpu-clock is a high-resolution per-CPU
+timer. See perf_event_open(2) for more details.
+
 CSV FORMAT
 ----------
 
@@ -671,4 +681,4 @@ that can be used for parsing.
 
 SEE ALSO
 --------
-linkperf:perf-top[1], linkperf:perf-list[1]
+linkperf:perf-top[1], linkperf:perf-list[1], perf_event_open(2)
-- 
2.34.1

Re: [PATCH] perf stat: document task-clock/cpu-clock in TIMINGS

[Ian Rogers]

On Wed, Sep 23, 2026 at 6:52 AM Christian Melendez <chrismelnu@gmail.com> wrote:
>
> task-clock/cpu-clock appear in perf stat's own example output but
> were never explained in perf-stat.txt, unlike time elapsed/user/sys.
> This came up unanswered on the list in 2013 and 2015 without docs
> ever being added.
>
> Link: https://patch.msgid.link/CAP-5=fV0-yvc68BUSKoSajHjHY_A6COgbEJYiFxRg+G-8LeJhQ@mail.gmail.com
> Signed-off-by: Christian Melendez <chrismelnu@gmail.com>

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

Thanks,
Ian

> ---
>  tools/perf/Documentation/perf-stat.txt | 12 +++++++++++-
>  1 file changed, 11 insertions(+), 1 deletion(-)
>
> diff --git a/tools/perf/Documentation/perf-stat.txt b/tools/perf/Documentation/perf-stat.txt
> index f334aabdc809..c0d6c344f9eb 100644
> --- a/tools/perf/Documentation/perf-stat.txt
> +++ b/tools/perf/Documentation/perf-stat.txt
> @@ -621,6 +621,16 @@ user/system lands:
>
>  Those times are the very same as displayed by the 'time' tool.
>
> +We also display a clock-based timing metric that depends on the
> +target being monitored:
> +
> +        83723.452481      task-clock:u (msec)       #    1.004 CPUs utilized
> +
> +For a single task, task-clock reports a clock count specific to that
> +task. When the target is a CPU or the whole system (-a or -C),
> +cpu-clock is reported instead. cpu-clock is a high-resolution per-CPU
> +timer. See perf_event_open(2) for more details.
> +
>  CSV FORMAT
>  ----------
>
> @@ -671,4 +681,4 @@ that can be used for parsing.
>
>  SEE ALSO
>  --------
> -linkperf:perf-top[1], linkperf:perf-list[1]
> +linkperf:perf-top[1], linkperf:perf-list[1], perf_event_open(2)
> --
> 2.34.1
>