Commit 348b7ca8 authored by Bagas Sanjaya's avatar Bagas Sanjaya Committed by Jonathan Corbet
Browse files

Documentation: trace: histogram: Fix histogram trigger subsection number order 



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  b8df4a36
("tracing: Move hist trigger Documentation to histogram.txt").

Fix the order.

Reviewed-by: default avatarTom Zanussi <zanussi@kernel.org>
Reviewed-by: default avatarMasami Hiramatsu (Google) <mhiramat@kernel.org>
Signed-off-by: default avatarBagas Sanjaya <bagasdotme@gmail.com>
Acked-by: default avatarSteven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Message-ID: <20250916054202.582074-3-bagasdotme@gmail.com>
parent 395107a7

Documentation/trace/histogram.rst

+17 −17
Original line number Diff line number Diff line
@@ -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