Documentation/trace/histogram.rst

File Facts

System

Linux kernel

Corpus path

Documentation/trace/histogram.rst

Extension

.rst

Size

163550 bytes

Lines

3072

Domain

Support Tooling And Documentation

Bucket

Documentation

Inferred role

Support Tooling And Documentation: documentation

Status

atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

• Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.
• Uses kernel synchronization; read lock ordering, sleepability, and interrupt context assumptions before translating.
• Allocates kernel memory; connect allocation flags and lifetime to context constraints.

Dependency Surface

• No C-style include directives detected by the generator.

Detected Declarations

• function event

Annotated Snippet

vfs_read+0x86/0x140
         SyS_read+0x46/0xb0
         system_call_fastpath+0x12/0x6a
    } hitcount:      19133  bytes_req:   78368768  bytes_alloc:   78368768

    Totals:
        Hits: 6085872
        Entries: 253
        Dropped: 0

  If you key a hist trigger on common_pid, in order for example to
  gather and display sorted totals for each process, you can use the
  special .execname modifier to display the executable names for the
  processes in the table rather than raw pids.  The example below
  keeps a per-process sum of total bytes read::

    # echo 'hist:key=common_pid.execname:val=count:sort=count.descending' > \
           /sys/kernel/tracing/events/syscalls/sys_enter_read/trigger

    # cat /sys/kernel/tracing/events/syscalls/sys_enter_read/hist
    # trigger info: hist:keys=common_pid.execname:vals=count:sort=count.descending:size=2048 [active]

    { common_pid: gnome-terminal  [      3196] } hitcount:        280  count:    1093512
    { common_pid: Xorg            [      1309] } hitcount:        525  count:     256640
    { common_pid: compiz          [      2889] } hitcount:         59  count:     254400
    { common_pid: bash            [      8710] } hitcount:          3  count:      66369
    { common_pid: dbus-daemon-lau [      8703] } hitcount:         49  count:      47739
    { common_pid: irqbalance      [      1252] } hitcount:         27  count:      27648
    { common_pid: 01ifupdown      [      8705] } hitcount:          3  count:      17216
    { common_pid: dbus-daemon     [       772] } hitcount:         10  count:      12396
    { common_pid: Socket Thread   [      8342] } hitcount:         11  count:      11264
    { common_pid: nm-dhcp-client. [      8701] } hitcount:          6  count:       7424
    { common_pid: gmain           [      1315] } hitcount:         18  count:       6336
    .
    .
    .
    { common_pid: postgres        [      1892] } hitcount:          2  count:         32
    { common_pid: postgres        [      1891] } hitcount:          2  count:         32
    { common_pid: gmain           [      8704] } hitcount:          2  count:         32
    { common_pid: upstart-dbus-br [      2740] } hitcount:         21  count:         21
    { common_pid: nm-dispatcher.a [      8696] } hitcount:          1  count:         16
    { common_pid: indicator-datet [      2904] } hitcount:          1  count:         16
    { common_pid: gdbus           [      2998] } hitcount:          1  count:         16
    { common_pid: rtkit-daemon    [      2052] } hitcount:          1  count:          8
    { common_pid: init            [         1] } hitcount:          2  count:          2

    Totals:
        Hits: 2116
        Entries: 51
        Dropped: 0

  Similarly, if you key a hist trigger on syscall id, for example to
  gather and display a list of systemwide syscall hits, you can use
  the special .syscall modifier to display the syscall names rather
  than raw ids.  The example below keeps a running total of syscall
  counts for the system during the run::

    # echo 'hist:key=id.syscall:val=hitcount' > \
           /sys/kernel/tracing/events/raw_syscalls/sys_enter/trigger

    # cat /sys/kernel/tracing/events/raw_syscalls/sys_enter/hist
    # trigger info: hist:keys=id.syscall:vals=hitcount:sort=hitcount:size=2048 [active]

    { id: sys_fsync                     [ 74] } hitcount:          1
    { id: sys_newuname                  [ 63] } hitcount:          1
    { id: sys_prctl                     [157] } hitcount:          1
    { id: sys_statfs                    [137] } hitcount:          1
    { id: sys_symlink                   [ 88] } hitcount:          1
    { id: sys_sendmmsg                  [307] } hitcount:          1
    { id: sys_semctl                    [ 66] } hitcount:          1

Annotation

• Detected declarations: `function event`.
• Atlas domain: Support Tooling And Documentation / Documentation.
• Implementation status: atlas-only.
• Synchronization appears in or near this file; preserve lock ordering, sleepability, and interrupt-context constraints.

Implementation Notes

• This generated page is the file-by-file coverage layer; curated subsystem chapters should link here when they synthesize a multi-file control flow.
• Core OS pages should be promoted from atlas-only to deep-reviewed when they explain data structures, invariants, locking, lifecycle, and C implementation snippets.
• Driver-family pages are intentionally pattern-oriented unless they are part of the selected PCIe/NVMe representative device path.