1 =============================
2 Per-task statistics interface
3 =============================
4
5
6 Taskstats is a netlink-based interface for sen
7 per-process statistics from the kernel to user
8
9 Taskstats was designed for the following benef
10
11 - efficiently provide statistics during lifeti
12 - unified interface for multiple accounting su
13 - extensibility for use by future accounting p
14
15 Terminology
16 -----------
17
18 "pid", "tid" and "task" are used interchangeab
19 Linux task defined by struct task_struct. per
20 per-task stats.
21
22 "tgid", "process" and "thread group" are used
23 tasks that share an mm_struct i.e. the traditi
24 use of tgid, there is no special treatment for
25 leader - a process is deemed alive as long as
26
27 Usage
28 -----
29
30 To get statistics during a task's lifetime, us
31 socket (NETLINK_GENERIC family) and sends comm
32 The response contains statistics for a task (i
33 statistics for all tasks of the process (if tg
34
35 To obtain statistics for tasks which are exiti
36 sends a register command and specifies a cpuma
37 one of the cpus in the cpumask, its per-pid st
38 registered listener. Using cpumasks allows the
39 to be limited and assists in flow control over
40 explained in more detail below.
41
42 If the exiting task is the last thread exiting
43 an additional record containing the per-tgid s
44 The latter contains the sum of per-pid stats f
45 group, both past and present.
46
47 getdelays.c is a simple utility demonstrating
48 for reporting delay accounting statistics. Use
49 send commands and process responses, listen fo
50 write the data received to a file and do basic
51 receive buffer sizes.
52
53 Interface
54 ---------
55
56 The user-kernel interface is encapsulated in i
57
58 To avoid this documentation becoming obsolete
59 an outline of the current version is given. ta
60 description here.
61
62 struct taskstats is the common accounting stru
63 per-tgid data. It is versioned and can be exte
64 that is added to the kernel. The fields and th
65 taskstats.h file.
66
67 The data exchanged between user and kernel spa
68 to the NETLINK_GENERIC family and using the ne
69 The messages are in the format::
70
71 +----------+- - -+-------------+----------
72 | nlmsghdr | Pad | genlmsghdr | taskstats
73 +----------+- - -+-------------+----------
74
75
76 The taskstats payload is one of the following
77
78 1. Commands: Sent from user to kernel. Command
79 a pid/tgid consist of one attribute, of type T
80 containing a u32 pid or tgid in the attribute
81 the task/process for which userspace wants sta
82
83 Commands to register/deregister interest in ex
84 consist of one attribute, of type
85 TASKSTATS_CMD_ATTR_REGISTER/DEREGISTER_CPUMASK
86 attribute payload. The cpumask is specified as
87 comma-separated cpu ranges e.g. to listen to e
88 the cpumask would be "1-3,5,7-8". If userspace
89 in cpus before closing the listening socket, t
90 set over time. However, for the sake of effici
91 is advisable.
92
93 2. Response for a command: sent from the kerne
94 command. The payload is a series of three attr
95
96 a) TASKSTATS_TYPE_AGGR_PID/TGID : attribute co
97 a pid/tgid will be followed by some stats.
98
99 b) TASKSTATS_TYPE_PID/TGID: attribute whose pa
100 are being returned.
101
102 c) TASKSTATS_TYPE_STATS: attribute with a stru
103 same structure is used for both per-pid and pe
104
105 3. New message sent by kernel whenever a task
106 series of attributes of the following type:
107
108 a) TASKSTATS_TYPE_AGGR_PID: indicates next two
109 b) TASKSTATS_TYPE_PID: contains exiting task's
110 c) TASKSTATS_TYPE_STATS: contains the exiting
111 d) TASKSTATS_TYPE_AGGR_TGID: indicates next tw
112 e) TASKSTATS_TYPE_TGID: contains tgid of proce
113 f) TASKSTATS_TYPE_STATS: contains the per-tgid
114
115
116 per-tgid stats
117 --------------
118
119 Taskstats provides per-process stats, in addit
120 resource management is often done at a process
121 stats in userspace alone is inefficient and po
122 of atomicity).
123
124 However, maintaining per-process, in addition
125 kernel has space and time overheads. To addres
126 accumulates each exiting task's statistics int
127 When the last task of a process exits, the pro
128 gets sent to userspace (along with the per-tas
129
130 When a user queries to get per-tgid data, the
131 the group is added up and added to the accumul
132 threads of the same thread group.
133
134 Extending taskstats
135 -------------------
136
137 There are two ways to extend the taskstats int
138 per-task/process stats as patches to collect t
139 in future:
140
141 1. Adding more fields to the end of the existi
142 compatibility is ensured by the version num
143 structure. Userspace will use only the fiel
144 to the version its using.
145
146 2. Defining separate statistic structs and usi
147 interface to return them. Since userspace p
148 independently, it can always ignore attribu
149 understand (because it is using an older ve
150
151
152 Choosing between 1. and 2. is a matter of trad
153 overhead. If only a few fields need to be adde
154 path since the kernel and userspace don't need
155 processing new netlink attributes. But if the
156 struct too much, requiring disparate userspace
157 unnecessarily receive large structures whose f
158 extending the attributes structure would be wo
159
160 Flow control for taskstats
161 --------------------------
162
163 When the rate of task exits becomes large, a l
164 up with the kernel's rate of sending per-tid/t
165 loss. This possibility gets compounded when th
166 extended and the number of cpus grows large.
167
168 To avoid losing statistics, userspace should d
169
170 - increase the receive buffer sizes for the ne
171 listeners to receive exit data.
172
173 - create more listeners and reduce the number
174 each listener. In the extreme case, there co
175 Users may also consider setting the cpu affi
176 of cpus to which it listens, especially if t
177
178 Despite these measures, if the userspace recei
179 indicated overflow of receive buffers, it shou
180 loss of data.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.