man/man5/proc_timer_stats.5

   1 .\" Copyright (C) 1994, 1995, Daniel Quinlan <quinlan@yggdrasil.com>
   2 .\" Copyright (C) 2002-2008, 2017, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\" Copyright (C) 2023, Alejandro Colomar <alx@kernel.org>
   4 .\"
   5 .\" SPDX-License-Identifier: GPL-3.0-or-later
   6 .\"
   7 .TH proc_timer_stats 5 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 /proc/timer_stats \- timer statistics
  10 .SH DESCRIPTION
  11 .TP
  12 .IR /proc/timer_stats " (from  Linux 2.6.21 until Linux 4.10)"
  13 .\" commit 82f67cd9fca8c8762c15ba7ed0d5747588c1e221
  14 .\"     Date:   Fri Feb 16 01:28:13 2007 -0800
  15 .\" Text largely derived from Documentation/timers/timer_stats.txt
  16 .\" removed in commit dfb4357da6ddbdf57d583ba64361c9d792b0e0b1
  17 .\"     Date:   Wed Feb 8 11:26:59 2017 -0800
  18 This is a debugging facility to make timer (ab)use in a Linux
  19 system visible to kernel and user-space developers.
  20 It can be used by kernel and user-space developers to verify that
  21 their code does not make undue use of timers.
  22 The goal is to avoid unnecessary wakeups,
  23 thereby optimizing power consumption.
  24 .IP
  25 If enabled in the kernel
  26 .RB ( CONFIG_TIMER_STATS ),
  27 but not used,
  28 it has almost zero run-time overhead and a relatively small
  29 data-structure overhead.
  30 Even if collection is enabled at run time, overhead is low:
  31 all the locking is per-CPU and lookup is hashed.
  32 .IP
  33 The
  34 .I /proc/timer_stats
  35 file is used both to control sampling facility and to read out the
  36 sampled information.
  37 .IP
  38 The
  39 .I timer_stats
  40 functionality is inactive on bootup.
  41 A sampling period can be started using the following command:
  42 .IP
  43 .in +4n
  44 .EX
  45 # echo 1 > /proc/timer_stats
  46 .EE
  47 .in
  48 .IP
  49 The following command stops a sampling period:
  50 .IP
  51 .in +4n
  52 .EX
  53 # echo 0 > /proc/timer_stats
  54 .EE
  55 .in
  56 .IP
  57 The statistics can be retrieved by:
  58 .IP
  59 .in +4n
  60 .EX
  61 $ cat /proc/timer_stats
  62 .EE
  63 .in
  64 .IP
  65 While sampling is enabled, each readout from
  66 .I /proc/timer_stats
  67 will see
  68 newly updated statistics.
  69 Once sampling is disabled, the sampled information
  70 is kept until a new sample period is started.
  71 This allows multiple readouts.
  72 .IP
  73 Sample output from
  74 .IR /proc/timer_stats :
  75 .IP
  76 .in +4n
  77 .EX
  78 .RB $ " cat /proc/timer_stats"
  79 Timer Stats Version: v0.3
  80 Sample period: 1.764 s
  81 Collection: active
  82   255,     0 swapper/3        hrtimer_start_range_ns (tick_sched_timer)
  83    71,     0 swapper/1        hrtimer_start_range_ns (tick_sched_timer)
  84    58,     0 swapper/0        hrtimer_start_range_ns (tick_sched_timer)
  85     4,  1694 gnome\-shell      mod_delayed_work_on (delayed_work_timer_fn)
  86    17,     7 rcu_sched        rcu_gp_kthread (process_timeout)
  87 \&...
  88     1,  4911 kworker/u16:0    mod_delayed_work_on (delayed_work_timer_fn)
  89    1D,  2522 kworker/0:0      queue_delayed_work_on (delayed_work_timer_fn)
  90 1029 total events, 583.333 events/sec
  91 .EE
  92 .in
  93 .IP
  94 The output columns are:
  95 .RS
  96 .IP [1] 5
  97 a count of the number of events,
  98 optionally (since Linux 2.6.23) followed by the letter \[aq]D\[aq]
  99 .\" commit c5c061b8f9726bc2c25e19dec227933a13d1e6b7 deferrable timers
 100 if this is a deferrable timer;
 101 .IP [2]
 102 the PID of the process that initialized the timer;
 103 .IP [3]
 104 the name of the process that initialized the timer;
 105 .IP [4]
 106 the function where the timer was initialized; and
 107 (in parentheses)
 108 the callback function that is associated with the timer.
 109 .RE
 110 .IP
 111 During the Linux 4.11 development cycle,
 112 this file  was removed because of security concerns,
 113 as it exposes information across namespaces.
 114 Furthermore, it is possible to obtain
 115 the same information via in-kernel tracing facilities such as ftrace.
 116 .SH SEE ALSO
 117 .BR proc (5)