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. This
20 requires CAP_PERFMON due to the event persisting, otherwise -EPERM is returned.
22 Typically programs will register a set of events that they wish to expose to
23 tools that can read trace_events (such as ftrace and perf). The registration
24 process tells the kernel which address and bit to reflect if any tool has
25 enabled the event and data should be written. The registration will give back
26 a write index which describes the data when a write() or writev() is called
27 on the /sys/kernel/tracing/user_events_data file.
29 The structures referenced in this document are contained within the
30 /include/uapi/linux/user_events.h file in the source tree.
32 **NOTE:** *Both user_events_status and user_events_data are under the tracefs
33 filesystem and may be mounted at different paths than above.*
37 Registering within a user process is done via ioctl() out to the
38 /sys/kernel/tracing/user_events_data file. The command to issue is
41 This command takes a packed struct user_reg as an argument::
44 /* Input: Size of the user_reg structure being used */
47 /* Input: Bit in enable address to use */
50 /* Input: Enable size in bytes at address */
53 /* Input: Flags to use, if any */
56 /* Input: Address to update when enabled */
59 /* Input: Pointer to string with event name, description and flags */
62 /* Output: Index of the event to use when writing data */
64 } __attribute__((__packed__));
66 The struct user_reg requires all the above inputs to be set appropriately.
68 + size: This must be set to sizeof(struct user_reg).
70 + enable_bit: The bit to reflect the event status at the address specified by
73 + enable_size: The size of the value specified by enable_addr.
74 This must be 4 (32-bit) or 8 (64-bit). 64-bit values are only allowed to be
75 used on 64-bit kernels, however, 32-bit can be used on all kernels.
77 + flags: The flags to use, if any.
78 Callers should first attempt to use flags and retry without flags to ensure
79 support for lower versions of the kernel. If a flag is not supported -EINVAL
82 + enable_addr: The address of the value to use to reflect event status. This
83 must be naturally aligned and write accessible within the user program.
85 + name_args: The name and arguments to describe the event, see command format
88 The following flags are currently supported.
90 + USER_EVENT_REG_PERSIST: The event will not delete upon the last reference
91 closing. Callers may use this if an event should exist even after the
92 process closes or unregisters the event. Requires CAP_PERFMON otherwise
95 Upon successful registration the following is set.
97 + write_index: The index to use for this file descriptor that represents this
98 event when writing out data. The index is unique to this instance of the file
99 descriptor that was used for the registration. See writing data for details.
101 User based events show up under tracefs like any other event under the
102 subsystem named "user_events". This means tools that wish to attach to the
103 events need to use /sys/kernel/tracing/events/user_events/[name]/enable
104 or perf record -e user_events:[name] when attaching/recording.
106 **NOTE:** The event subsystem name by default is "user_events". Callers should
107 not assume it will always be "user_events". Operators reserve the right in the
108 future to change the subsystem name per-process to accommodate event isolation.
112 The command string format is as follows::
114 name[:FLAG1[,FLAG2...]] [Field1[;Field2...]]
126 Basic types are supported (__data_loc, u32, u64, int, char, char[20], etc).
127 User programs are encouraged to use clearly sized types like u32.
129 **NOTE:** *Long is not supported since size can vary between user and kernel.*
131 The size is only valid for types that start with a struct prefix.
132 This allows user programs to describe custom structs out to tools, if required.
134 For example, a struct in C that looks like this::
140 Would be represented by the following field::
142 struct mytype myname 20
146 Deleting an event from within a user process is done via ioctl() out to the
147 /sys/kernel/tracing/user_events_data file. The command to issue is
150 This command only requires a single string specifying the event to delete by
151 its name. Delete will only succeed if there are no references left to the
152 event (in both user and kernel space). User programs should use a separate file
153 to request deletes than the one used for registration due to this.
155 **NOTE:** By default events will auto-delete when there are no references left
156 to the event. If programs do not want auto-delete, they must use the
157 USER_EVENT_REG_PERSIST flag when registering the event. Once that flag is used
158 the event exists until DIAG_IOCSDEL is invoked. Both register and delete of an
159 event that persists requires CAP_PERFMON, otherwise -EPERM is returned.
163 If after registering an event it is no longer wanted to be updated then it can
164 be disabled via ioctl() out to the /sys/kernel/tracing/user_events_data file.
165 The command to issue is DIAG_IOCSUNREG. This is different than deleting, where
166 deleting actually removes the event from the system. Unregistering simply tells
167 the kernel your process is no longer interested in updates to the event.
169 This command takes a packed struct user_unreg as an argument::
172 /* Input: Size of the user_unreg structure being used */
175 /* Input: Bit to unregister */
178 /* Input: Reserved, set to 0 */
181 /* Input: Reserved, set to 0 */
184 /* Input: Address to unregister */
186 } __attribute__((__packed__));
188 The struct user_unreg requires all the above inputs to be set appropriately.
190 + size: This must be set to sizeof(struct user_unreg).
192 + disable_bit: This must be set to the bit to disable (same bit that was
193 previously registered via enable_bit).
195 + disable_addr: This must be set to the address to disable (same address that was
196 previously registered via enable_addr).
198 **NOTE:** Events are automatically unregistered when execve() is invoked. During
199 fork() the registered events will be retained and must be unregistered manually
200 in each process if wanted.
204 When tools attach/record user based events the status of the event is updated
205 in realtime. This allows user programs to only incur the cost of the write() or
206 writev() calls when something is actively attached to the event.
208 The kernel will update the specified bit that was registered for the event as
209 tools attach/detach from the event. User programs simply check if the bit is set
210 to see if something is attached or not.
212 Administrators can easily check the status of all registered events by reading
213 the user_events_status file directly via a terminal. The output is as follows::
221 For example, on a system that has a single event the output looks like this::
228 If a user enables the user event via ftrace, the output would change to this::
230 test # Used by ftrace
237 After registering an event the same fd that was used to register can be used
238 to write an entry for that event. The write_index returned must be at the start
239 of the data, then the remaining data is treated as the payload of the event.
241 For example, if write_index returned was 1 and I wanted to write out an int
242 payload of the event. Then the data would have to be 8 bytes (2 ints) in size,
243 with the first 4 bytes being equal to 1 and the last 4 bytes being equal to the
244 value I want as the payload.
246 In memory this would look like this::
251 User programs might have well known structs that they wish to use to emit out
252 as payloads. In those cases writev() can be used, with the first vector being
253 the index and the following vector(s) being the actual event payload.
255 For example, if I have a struct like this::
261 } __attribute__((__packed__));
263 It's advised for user programs to do the following::
268 io[0].iov_base = &write_index;
269 io[0].iov_len = sizeof(write_index);
271 io[1].iov_len = sizeof(e);
273 writev(fd, (const struct iovec*)io, 2);
275 **NOTE:** *The write_index is not emitted out into the trace being recorded.*
279 See sample code in samples/user_events.