Re: [PATCH 1/5] Documentation: trace: histogram: Fix histogram trigger subsection number order

Masami Hiramatsu
2025-09-12T00:59:37Z

On Thu, 11 Sep 2025 11:25:23 +0700
Bagas Sanjaya <bagasdotme@gmail.com> wrote:

> Section numbering in subsections of "Histogram Trigger Command" sections
> is inconsistent in order. In particular, "'hist' trigger examples" is
> erroneously numbered as 6.2, which is a leftover from b8df4a3634e08a
> ("tracing: Move hist trigger Documentation to histogram.txt").
>
> Fix the order.

Thanks for fixing. This looks good to me.

Reviewed-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>

Thanks,

>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
> Documentation/trace/histogram.rst | 34 +++++++++++++++----------------
> 1 file changed, 17 insertions(+), 17 deletions(-)
>
> diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst
> index af6d2e15568ebd..d158dadaa42447 100644
> --- a/Documentation/trace/histogram.rst
> +++ b/Documentation/trace/histogram.rst
> @@ -186,8 +186,8 @@ Documentation written by Tom Zanussi
> The examples below provide a more concrete illustration of the
> concepts and typical usage patterns discussed above.
>
> -'special' event fields
> -------------------------
> +2.1. 'special' event fields
> +---------------------------
>
> There are a number of 'special event fields' available for use as
> keys or values in a hist trigger. These look like and behave as if
> @@ -204,16 +204,16 @@ Documentation written by Tom Zanussi
> common_cpu int the cpu on which the event occurred.
> ====================== ==== =======================================
>
> -Extended error information
> ---------------------------
> +2.2. Extended error information
> +-------------------------------
>
> For some error conditions encountered when invoking a hist trigger
> command, extended error information is available via the
> tracing/error_log file. See Error Conditions in
> :file:`Documentation/trace/ftrace.rst` for details.
>
> -6.2 'hist' trigger examples
> ----------------------------
> +2.3. 'hist' trigger examples
> +----------------------------
>
> The first set of examples creates aggregations using the kmalloc
> event. The fields that can be used for the hist trigger are listed
> @@ -1608,8 +1608,8 @@ Extended error information
> Entries: 7
> Dropped: 0
>
> -2.2 Inter-event hist triggers
> ------------------------------
> +2.4. Inter-event hist triggers
> +------------------------------
>
> Inter-event hist triggers are hist triggers that combine values from
> one or more other events and create a histogram using that data. Data
> @@ -1685,8 +1685,8 @@ pseudo-file.
>
> These features are described in more detail in the following sections.
>
> -2.2.1 Histogram Variables
> --------------------------
> +2.5. Histogram Variables
> +------------------------
>
> Variables are simply named locations used for saving and retrieving
> values between matching events. A 'matching' event is defined as an
> @@ -1789,8 +1789,8 @@ or assigned to a variable and referenced in a subsequent expression::
>
> Variables can even hold stacktraces, which are useful with synthetic events.
>
> -2.2.2 Synthetic Events
> -----------------------
> +2.6. Synthetic Events
> +---------------------
>
> Synthetic events are user-defined events generated from hist trigger
> variables or fields associated with one or more other events. Their
> @@ -1846,7 +1846,7 @@ the command that defined it with a '!'::
> At this point, there isn't yet an actual 'wakeup_latency' event
> instantiated in the event subsystem - for this to happen, a 'hist
> trigger action' needs to be instantiated and bound to actual fields
> -and variables defined on other events (see Section 2.2.3 below on
> +and variables defined on other events (see Section 2.7. below on
> how that is done using hist trigger 'onmatch' action). Once that is
> done, the 'wakeup_latency' synthetic event instance is created.
>
> @@ -2094,8 +2094,8 @@ histogram::
> Entries: 7
> Dropped: 0
>
> -2.2.3 Hist trigger 'handlers' and 'actions'
> --------------------------------------------
> +2.7. Hist trigger 'handlers' and 'actions'
> +------------------------------------------
>
> A hist trigger 'action' is a function that's executed (in most cases
> conditionally) whenever a histogram entry is added or updated.
> @@ -2526,8 +2526,8 @@ The following commonly-used handler.action pairs are available:
> kworker/3:2-135 [003] d..3 49.823123: sched_switch: prev_comm=kworker/3:2 prev_pid=135 prev_prio=120 prev_state=T ==> next_comm=swapper/3 next_pid=0 next_prio=120
> <idle>-0 [004] ..s7 49.823798: tcp_probe: src=10.0.0.10:54326 dest=23.215.104.193:80 mark=0x0 length=32 snd_nxt=0xe3ae2ff5 snd_una=0xe3ae2ecd snd_cwnd=10 ssthresh=2147483647 snd_wnd=28960 srtt=19604 rcv_wnd=29312
>
> -3. User space creating a trigger
> ---------------------------------
> +2.8. User space creating a trigger
> +----------------------------------
>
> Writing into /sys/kernel/tracing/trace_marker writes into the ftrace
> ring buffer. This can also act like an event, by writing into the trigger
> --
> An old man doll... just what I always wanted! - Clara
>

--
Masami Hiramatsu (Google) <mhiramat@kernel.org>