[PATCH] per-task-delay-accounting: documentation
[linux-2.6.git] / 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, two records are sent by the kernel to
36 each listener on the multicast socket. The first the per-pid task's statistics
37 and the second is the sum for all tasks of the process to which the task
38 belongs (the task does not need to be the thread group leader). The need for
39 per-tgid stats to be sent for each exiting task is explained in the per-tgid
40 stats section below.
41
42 getdelays.c is a simple utility demonstrating usage of the taskstats interface
43 for reporting delay accounting statistics.
44
45 Interface
46 ---------
47
48 The user-kernel interface is encapsulated in include/linux/taskstats.h
49
50 To avoid this documentation becoming obsolete as the interface evolves, only
51 an outline of the current version is given. taskstats.h always overrides the
52 description here.
53
54 struct taskstats is the common accounting structure for both per-pid and
55 per-tgid data. It is versioned and can be extended by each accounting subsystem
56 that is added to the kernel. The fields and their semantics are defined in the
57 taskstats.h file.
58
59 The data exchanged between user and kernel space is a netlink message belonging
60 to the NETLINK_GENERIC family and using the netlink attributes interface.
61 The messages are in the format
62
63     +----------+- - -+-------------+-------------------+
64     | nlmsghdr | Pad |  genlmsghdr | taskstats payload |
65     +----------+- - -+-------------+-------------------+
66
67
68 The taskstats payload is one of the following three kinds:
69
70 1. Commands: Sent from user to kernel. The payload is one attribute, of type
71 TASKSTATS_CMD_ATTR_PID/TGID, containing a u32 pid or tgid in the attribute
72 payload. The pid/tgid denotes the task/process for which userspace wants
73 statistics.
74
75 2. Response for a command: sent from the kernel in response to a userspace
76 command. The payload is a series of three attributes of type:
77
78 a) TASKSTATS_TYPE_AGGR_PID/TGID : attribute containing no payload but indicates
79 a pid/tgid will be followed by some stats.
80
81 b) TASKSTATS_TYPE_PID/TGID: attribute whose payload is the pid/tgid whose stats
82 is being returned.
83
84 c) TASKSTATS_TYPE_STATS: attribute with a struct taskstsats as payload. The
85 same structure is used for both per-pid and per-tgid stats.
86
87 3. New message sent by kernel whenever a task exits. The payload consists of a
88    series of attributes of the following type:
89
90 a) TASKSTATS_TYPE_AGGR_PID: indicates next two attributes will be pid+stats
91 b) TASKSTATS_TYPE_PID: contains exiting task's pid
92 c) TASKSTATS_TYPE_STATS: contains the exiting task's per-pid stats
93 d) TASKSTATS_TYPE_AGGR_TGID: indicates next two attributes will be tgid+stats
94 e) TASKSTATS_TYPE_TGID: contains tgid of process to which task belongs
95 f) TASKSTATS_TYPE_STATS: contains the per-tgid stats for exiting task's process
96
97
98 per-tgid stats
99 --------------
100
101 Taskstats provides per-process stats, in addition to per-task stats, since
102 resource management is often done at a process granularity and aggregating task
103 stats in userspace alone is inefficient and potentially inaccurate (due to lack
104 of atomicity).
105
106 However, maintaining per-process, in addition to per-task stats, within the
107 kernel has space and time overheads. Hence the taskstats implementation
108 dynamically sums up the per-task stats for each task belonging to a process
109 whenever per-process stats are needed.
110
111 Not maintaining per-tgid stats creates a problem when userspace is interested
112 in getting these stats when the process dies i.e. the last thread of
113 a process exits. It isn't possible to simply return some aggregated per-process
114 statistic from the kernel.
115
116 The approach taken by taskstats is to return the per-tgid stats *each* time
117 a task exits, in addition to the per-pid stats for that task. Userspace can
118 maintain task<->process mappings and use them to maintain the per-process stats
119 in userspace, updating the aggregate appropriately as the tasks of a process
120 exit.
121
122 Extending taskstats
123 -------------------
124
125 There are two ways to extend the taskstats interface to export more
126 per-task/process stats as patches to collect them get added to the kernel
127 in future:
128
129 1. Adding more fields to the end of the existing struct taskstats. Backward
130    compatibility is ensured by the version number within the
131    structure. Userspace will use only the fields of the struct that correspond
132    to the version its using.
133
134 2. Defining separate statistic structs and using the netlink attributes
135    interface to return them. Since userspace processes each netlink attribute
136    independently, it can always ignore attributes whose type it does not
137    understand (because it is using an older version of the interface).
138
139
140 Choosing between 1. and 2. is a matter of trading off flexibility and
141 overhead. If only a few fields need to be added, then 1. is the preferable
142 path since the kernel and userspace don't need to incur the overhead of
143 processing new netlink attributes. But if the new fields expand the existing
144 struct too much, requiring disparate userspace accounting utilities to
145 unnecessarily receive large structures whose fields are of no interest, then
146 extending the attributes structure would be worthwhile.
147
148 ----