Documentation/accounting/taskstats.txt

   1 Per-task statistics interface
   2 -----------------------------
   3
   4
   5 Taskstats is a netlink-based interface for sending per-task and
   6 per-process statistics from the kernel to userspace.
   7
   8 Taskstats was designed for the following benefits:
   9
  10 - efficiently provide statistics during lifetime of a task and on its exit
  11 - unified interface for multiple accounting subsystems
  12 - extensibility for use by future accounting patches
  13
  14 Terminology
  15 -----------
  16
  17 "pid", "tid" and "task" are used interchangeably and refer to the standard
  18 Linux task defined by struct task_struct.  per-pid stats are the same as
  19 per-task stats.
  20
  21 "tgid", "process" and "thread group" are used interchangeably and refer to the
  22 tasks that share an mm_struct i.e. the traditional Unix process. Despite the
  23 use of tgid, there is no special treatment for the task that is thread group
  24 leader - a process is deemed alive as long as it has any task belonging to it.
  25
  26 Usage
  27 -----
  28
  29 To get statistics during task's lifetime, userspace opens a unicast netlink
  30 socket (NETLINK_GENERIC family) and sends commands specifying a pid or a tgid.
  31 The response contains statistics for a task (if pid is specified) or the sum of
  32 statistics for all tasks of the process (if tgid is specified).
  33
  34 To obtain statistics for tasks which are exiting, userspace opens a multicast
  35 netlink socket. Each time a task exits, its per-pid statistics is always sent
  36 by the kernel to each listener on the multicast socket. In addition, if it is
  37 the last thread exiting its thread group, an additional record containing the
  38 per-tgid stats are also sent. The latter contains the sum of per-pid stats for
  39 all threads in the thread group, both past and present.
  40
  41 getdelays.c is a simple utility demonstrating usage of the taskstats interface
  42 for reporting delay accounting statistics.
  43
  44 Interface
  45 ---------
  46
  47 The user-kernel interface is encapsulated in include/linux/taskstats.h
  48
  49 To avoid this documentation becoming obsolete as the interface evolves, only
  50 an outline of the current version is given. taskstats.h always overrides the
  51 description here.
  52
  53 struct taskstats is the common accounting structure for both per-pid and
  54 per-tgid data. It is versioned and can be extended by each accounting subsystem
  55 that is added to the kernel. The fields and their semantics are defined in the
  56 taskstats.h file.
  57
  58 The data exchanged between user and kernel space is a netlink message belonging
  59 to the NETLINK_GENERIC family and using the netlink attributes interface.
  60 The messages are in the format
  61
  62     +----------+- - -+-------------+-------------------+
  63     | nlmsghdr | Pad |  genlmsghdr | taskstats payload |
  64     +----------+- - -+-------------+-------------------+
  65
  66
  67 The taskstats payload is one of the following three kinds:
  68
  69 1. Commands: Sent from user to kernel. The payload is one attribute, of type
  70 TASKSTATS_CMD_ATTR_PID/TGID, containing a u32 pid or tgid in the attribute
  71 payload. The pid/tgid denotes the task/process for which userspace wants
  72 statistics.
  73
  74 2. Response for a command: sent from the kernel in response to a userspace
  75 command. The payload is a series of three attributes of type:
  76
  77 a) TASKSTATS_TYPE_AGGR_PID/TGID : attribute containing no payload but indicates
  78 a pid/tgid will be followed by some stats.
  79
  80 b) TASKSTATS_TYPE_PID/TGID: attribute whose payload is the pid/tgid whose stats
  81 is being returned.
  82
  83 c) TASKSTATS_TYPE_STATS: attribute with a struct taskstsats as payload. The
  84 same structure is used for both per-pid and per-tgid stats.
  85
  86 3. New message sent by kernel whenever a task exits. The payload consists of a
  87    series of attributes of the following type:
  88
  89 a) TASKSTATS_TYPE_AGGR_PID: indicates next two attributes will be pid+stats
  90 b) TASKSTATS_TYPE_PID: contains exiting task's pid
  91 c) TASKSTATS_TYPE_STATS: contains the exiting task's per-pid stats
  92 d) TASKSTATS_TYPE_AGGR_TGID: indicates next two attributes will be tgid+stats
  93 e) TASKSTATS_TYPE_TGID: contains tgid of process to which task belongs
  94 f) TASKSTATS_TYPE_STATS: contains the per-tgid stats for exiting task's process
  95
  96
  97 per-tgid stats
  98 --------------
  99
 100 Taskstats provides per-process stats, in addition to per-task stats, since
 101 resource management is often done at a process granularity and aggregating task
 102 stats in userspace alone is inefficient and potentially inaccurate (due to lack
 103 of atomicity).
 104
 105 However, maintaining per-process, in addition to per-task stats, within the
 106 kernel has space and time overheads. To address this, the taskstats code
 107 accumalates each exiting task's statistics into a process-wide data structure.
 108 When the last task of a process exits, the process level data accumalated also
 109 gets sent to userspace (along with the per-task data).
 110
 111 When a user queries to get per-tgid data, the sum of all other live threads in
 112 the group is added up and added to the accumalated total for previously exited
 113 threads of the same thread group.
 114
 115 Extending taskstats
 116 -------------------
 117
 118 There are two ways to extend the taskstats interface to export more
 119 per-task/process stats as patches to collect them get added to the kernel
 120 in future:
 121
 122 1. Adding more fields to the end of the existing struct taskstats. Backward
 123    compatibility is ensured by the version number within the
 124    structure. Userspace will use only the fields of the struct that correspond
 125    to the version its using.
 126
 127 2. Defining separate statistic structs and using the netlink attributes
 128    interface to return them. Since userspace processes each netlink attribute
 129    independently, it can always ignore attributes whose type it does not
 130    understand (because it is using an older version of the interface).
 131
 132
 133 Choosing between 1. and 2. is a matter of trading off flexibility and
 134 overhead. If only a few fields need to be added, then 1. is the preferable
 135 path since the kernel and userspace don't need to incur the overhead of
 136 processing new netlink attributes. But if the new fields expand the existing
 137 struct too much, requiring disparate userspace accounting utilities to
 138 unnecessarily receive large structures whose fields are of no interest, then
 139 extending the attributes structure would be worthwhile.
 140
 141 ----