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@xxxxxxxxx> 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
>