1 =========================================
2 user_events: User-based Event Tracing
3 =========================================
9 User based trace events allow user processes to create events and trace data
10 that can be viewed via existing tools, such as ftrace and perf.
11 To enable this feature, build your kernel with CONFIG_USER_EVENTS=y.
13 Programs can view status of the events via
14 /sys/kernel/tracing/user_events_status and can both register and write
15 data out via /sys/kernel/tracing/user_events_data.
17 Programs can also use /sys/kernel/tracing/dynamic_events to register and
18 delete user based events via the u: prefix. The format of the command to
19 dynamic_events is the same as the ioctl with the u: prefix applied.
21 Typically programs will register a set of events that they wish to expose to
22 tools that can read trace_events (such as ftrace and perf). The registration
23 process tells the kernel which address and bit to reflect if any tool has
24 enabled the event and data should be written. The registration will give back
25 a write index which describes the data when a write() or writev() is called
26 on the /sys/kernel/tracing/user_events_data file.
28 The structures referenced in this document are contained within the
29 /include/uapi/linux/user_events.h file in the source tree.
31 **NOTE:** *Both user_events_status and user_events_data are under the tracefs
32 filesystem and may be mounted at different paths than above.*
36 Registering within a user process is done via ioctl() out to the
37 /sys/kernel/tracing/user_events_data file. The command to issue is
40 This command takes a packed struct user_reg as an argument::
43 /* Input: Size of the user_reg structure being used */
46 /* Input: Bit in enable address to use */
49 /* Input: Enable size in bytes at address */
52 /* Input: Flags for future use, set to 0 */
55 /* Input: Address to update when enabled */
58 /* Input: Pointer to string with event name, description and flags */
61 /* Output: Index of the event to use when writing data */
63 } __attribute__((__packed__));
65 The struct user_reg requires all the above inputs to be set appropriately.
67 + size: This must be set to sizeof(struct user_reg).
69 + enable_bit: The bit to reflect the event status at the address specified by
72 + enable_size: The size of the value specified by enable_addr.
73 This must be 4 (32-bit) or 8 (64-bit). 64-bit values are only allowed to be
74 used on 64-bit kernels, however, 32-bit can be used on all kernels.
76 + flags: The flags to use, if any. For the initial version this must be 0.
77 Callers should first attempt to use flags and retry without flags to ensure
78 support for lower versions of the kernel. If a flag is not supported -EINVAL
81 + enable_addr: The address of the value to use to reflect event status. This
82 must be naturally aligned and write accessible within the user program.
84 + name_args: The name and arguments to describe the event, see command format
87 Upon successful registration the following is set.
89 + write_index: The index to use for this file descriptor that represents this
90 event when writing out data. The index is unique to this instance of the file
91 descriptor that was used for the registration. See writing data for details.
93 User based events show up under tracefs like any other event under the
94 subsystem named "user_events". This means tools that wish to attach to the
95 events need to use /sys/kernel/tracing/events/user_events/[name]/enable
96 or perf record -e user_events:[name] when attaching/recording.
98 **NOTE:** The event subsystem name by default is "user_events". Callers should
99 not assume it will always be "user_events". Operators reserve the right in the
100 future to change the subsystem name per-process to accomodate event isolation.
104 The command string format is as follows::
106 name[:FLAG1[,FLAG2...]] [Field1[;Field2...]]
118 Basic types are supported (__data_loc, u32, u64, int, char, char[20], etc).
119 User programs are encouraged to use clearly sized types like u32.
121 **NOTE:** *Long is not supported since size can vary between user and kernel.*
123 The size is only valid for types that start with a struct prefix.
124 This allows user programs to describe custom structs out to tools, if required.
126 For example, a struct in C that looks like this::
132 Would be represented by the following field::
134 struct mytype myname 20
138 Deleting an event from within a user process is done via ioctl() out to the
139 /sys/kernel/tracing/user_events_data file. The command to issue is
142 This command only requires a single string specifying the event to delete by
143 its name. Delete will only succeed if there are no references left to the
144 event (in both user and kernel space). User programs should use a separate file
145 to request deletes than the one used for registration due to this.
149 If after registering an event it is no longer wanted to be updated then it can
150 be disabled via ioctl() out to the /sys/kernel/tracing/user_events_data file.
151 The command to issue is DIAG_IOCSUNREG. This is different than deleting, where
152 deleting actually removes the event from the system. Unregistering simply tells
153 the kernel your process is no longer interested in updates to the event.
155 This command takes a packed struct user_unreg as an argument::
158 /* Input: Size of the user_unreg structure being used */
161 /* Input: Bit to unregister */
164 /* Input: Reserved, set to 0 */
167 /* Input: Reserved, set to 0 */
170 /* Input: Address to unregister */
172 } __attribute__((__packed__));
174 The struct user_unreg requires all the above inputs to be set appropriately.
176 + size: This must be set to sizeof(struct user_unreg).
178 + disable_bit: This must be set to the bit to disable (same bit that was
179 previously registered via enable_bit).
181 + disable_addr: This must be set to the address to disable (same address that was
182 previously registered via enable_addr).
184 **NOTE:** Events are automatically unregistered when execve() is invoked. During
185 fork() the registered events will be retained and must be unregistered manually
186 in each process if wanted.
190 When tools attach/record user based events the status of the event is updated
191 in realtime. This allows user programs to only incur the cost of the write() or
192 writev() calls when something is actively attached to the event.
194 The kernel will update the specified bit that was registered for the event as
195 tools attach/detach from the event. User programs simply check if the bit is set
196 to see if something is attached or not.
198 Administrators can easily check the status of all registered events by reading
199 the user_events_status file directly via a terminal. The output is as follows::
207 For example, on a system that has a single event the output looks like this::
214 If a user enables the user event via ftrace, the output would change to this::
216 test # Used by ftrace
223 After registering an event the same fd that was used to register can be used
224 to write an entry for that event. The write_index returned must be at the start
225 of the data, then the remaining data is treated as the payload of the event.
227 For example, if write_index returned was 1 and I wanted to write out an int
228 payload of the event. Then the data would have to be 8 bytes (2 ints) in size,
229 with the first 4 bytes being equal to 1 and the last 4 bytes being equal to the
230 value I want as the payload.
232 In memory this would look like this::
237 User programs might have well known structs that they wish to use to emit out
238 as payloads. In those cases writev() can be used, with the first vector being
239 the index and the following vector(s) being the actual event payload.
241 For example, if I have a struct like this::
247 } __attribute__((__packed__));
249 It's advised for user programs to do the following::
254 io[0].iov_base = &write_index;
255 io[0].iov_len = sizeof(write_index);
257 io[1].iov_len = sizeof(e);
259 writev(fd, (const struct iovec*)io, 2);
261 **NOTE:** *The write_index is not emitted out into the trace being recorded.*
265 See sample code in samples/user_events.