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
>

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

[Arnaldo Carvalho de Melo]

On Wed, Sep 23, 2026 at 08:14:09AM -0700, Ian Rogers wrote:
> 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, applied to perf-tools-next, for v7.4.

- Arnaldo

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

[Namhyung Kim]

Hello,

On Wed, Sep 23, 2026 at 03:51:40PM +0200, Christian Melendez 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>
> ---
>  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

I'm afraid task-clock and any other software events don't support
privilege filters or modifiers.  So task-clock:u would be same as
task-clock, but it can give a wrong idea that it only measured time
in userspace.

Maybe the kernel can reject ones with modifiers but then it would have
a compatibility issue. :(

So I think it's better to remove the ":u" modifier in the example
output.  Probably we need to change the perf not to add it to the
software events.

Thanks,
Namhyung

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

[Arnaldo Carvalho de Melo]

On Thu, Sep 24, 2026 at 03:23:57PM -0700, Namhyung Kim wrote:
> Hello,
> 
> On Wed, Sep 23, 2026 at 03:51:40PM +0200, Christian Melendez 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>
> > ---
> >  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
> 
> I'm afraid task-clock and any other software events don't support
> privilege filters or modifiers.  So task-clock:u would be same as
> task-clock, but it can give a wrong idea that it only measured time
> in userspace.
> 
> Maybe the kernel can reject ones with modifiers but then it would have
> a compatibility issue. :(
> 
> So I think it's better to remove the ":u" modifier in the example
> output.  Probably we need to change the perf not to add it to the
> software events.

Since I'll need to force push due to a missing Signed-off-by in a patch
that had --- markers before the author's Signed-off-by, I'll remove the
:u.

- Arnaldo
 
> Thanks,
> Namhyung
> 
> > +
> > +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
> >