Documentation/trace/user_events.rst

   1 =========================================
   2 user_events: User-based Event Tracing
   3 =========================================
   4
   5 :Author: Beau Belgrave
   6
   7 Overview
   8 --------
   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.
  12
  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.
  16
  17 Typically programs will register a set of events that they wish to expose to
  18 tools that can read trace_events (such as ftrace and perf). The registration
  19 process tells the kernel which address and bit to reflect if any tool has
  20 enabled the event and data should be written. The registration will give back
  21 a write index which describes the data when a write() or writev() is called
  22 on the /sys/kernel/tracing/user_events_data file.
  23
  24 The structures referenced in this document are contained within the
  25 /include/uapi/linux/user_events.h file in the source tree.
  26
  27 **NOTE:** *Both user_events_status and user_events_data are under the tracefs
  28 filesystem and may be mounted at different paths than above.*
  29
  30 Registering
  31 -----------
  32 Registering within a user process is done via ioctl() out to the
  33 /sys/kernel/tracing/user_events_data file. The command to issue is
  34 DIAG_IOCSREG.
  35
  36 This command takes a packed struct user_reg as an argument::
  37
  38   struct user_reg {
  39         /* Input: Size of the user_reg structure being used */
  40         __u32 size;
  41
  42         /* Input: Bit in enable address to use */
  43         __u8 enable_bit;
  44
  45         /* Input: Enable size in bytes at address */
  46         __u8 enable_size;
  47
  48         /* Input: Flags for future use, set to 0 */
  49         __u16 flags;
  50
  51         /* Input: Address to update when enabled */
  52         __u64 enable_addr;
  53
  54         /* Input: Pointer to string with event name, description and flags */
  55         __u64 name_args;
  56
  57         /* Output: Index of the event to use when writing data */
  58         __u32 write_index;
  59   } __attribute__((__packed__));
  60
  61 The struct user_reg requires all the above inputs to be set appropriately.
  62
  63 + size: This must be set to sizeof(struct user_reg).
  64
  65 + enable_bit: The bit to reflect the event status at the address specified by
  66   enable_addr.
  67
  68 + enable_size: The size of the value specified by enable_addr.
  69   This must be 4 (32-bit) or 8 (64-bit). 64-bit values are only allowed to be
  70   used on 64-bit kernels, however, 32-bit can be used on all kernels.
  71
  72 + flags: The flags to use, if any. For the initial version this must be 0.
  73   Callers should first attempt to use flags and retry without flags to ensure
  74   support for lower versions of the kernel. If a flag is not supported -EINVAL
  75   is returned.
  76
  77 + enable_addr: The address of the value to use to reflect event status. This
  78   must be naturally aligned and write accessible within the user program.
  79
  80 + name_args: The name and arguments to describe the event, see command format
  81   for details.
  82
  83 Upon successful registration the following is set.
  84
  85 + write_index: The index to use for this file descriptor that represents this
  86   event when writing out data. The index is unique to this instance of the file
  87   descriptor that was used for the registration. See writing data for details.
  88
  89 User based events show up under tracefs like any other event under the
  90 subsystem named "user_events". This means tools that wish to attach to the
  91 events need to use /sys/kernel/tracing/events/user_events/[name]/enable
  92 or perf record -e user_events:[name] when attaching/recording.
  93
  94 **NOTE:** The event subsystem name by default is "user_events". Callers should
  95 not assume it will always be "user_events". Operators reserve the right in the
  96 future to change the subsystem name per-process to accomodate event isolation.
  97
  98 Command Format
  99 ^^^^^^^^^^^^^^
 100 The command string format is as follows::
 101
 102   name[:FLAG1[,FLAG2...]] [Field1[;Field2...]]
 103
 104 Supported Flags
 105 ^^^^^^^^^^^^^^^
 106 None yet
 107
 108 Field Format
 109 ^^^^^^^^^^^^
 110 ::
 111
 112   type name [size]
 113
 114 Basic types are supported (__data_loc, u32, u64, int, char, char[20], etc).
 115 User programs are encouraged to use clearly sized types like u32.
 116
 117 **NOTE:** *Long is not supported since size can vary between user and kernel.*
 118
 119 The size is only valid for types that start with a struct prefix.
 120 This allows user programs to describe custom structs out to tools, if required.
 121
 122 For example, a struct in C that looks like this::
 123
 124   struct mytype {
 125     char data[20];
 126   };
 127
 128 Would be represented by the following field::
 129
 130   struct mytype myname 20
 131
 132 Deleting
 133 --------
 134 Deleting an event from within a user process is done via ioctl() out to the
 135 /sys/kernel/tracing/user_events_data file. The command to issue is
 136 DIAG_IOCSDEL.
 137
 138 This command only requires a single string specifying the event to delete by
 139 its name. Delete will only succeed if there are no references left to the
 140 event (in both user and kernel space). User programs should use a separate file
 141 to request deletes than the one used for registration due to this.
 142
 143 **NOTE:** By default events will auto-delete when there are no references left
 144 to the event. Flags in the future may change this logic.
 145
 146 Unregistering
 147 -------------
 148 If after registering an event it is no longer wanted to be updated then it can
 149 be disabled via ioctl() out to the /sys/kernel/tracing/user_events_data file.
 150 The command to issue is DIAG_IOCSUNREG. This is different than deleting, where
 151 deleting actually removes the event from the system. Unregistering simply tells
 152 the kernel your process is no longer interested in updates to the event.
 153
 154 This command takes a packed struct user_unreg as an argument::
 155
 156   struct user_unreg {
 157         /* Input: Size of the user_unreg structure being used */
 158         __u32 size;
 159
 160         /* Input: Bit to unregister */
 161         __u8 disable_bit;
 162
 163         /* Input: Reserved, set to 0 */
 164         __u8 __reserved;
 165
 166         /* Input: Reserved, set to 0 */
 167         __u16 __reserved2;
 168
 169         /* Input: Address to unregister */
 170         __u64 disable_addr;
 171   } __attribute__((__packed__));
 172
 173 The struct user_unreg requires all the above inputs to be set appropriately.
 174
 175 + size: This must be set to sizeof(struct user_unreg).
 176
 177 + disable_bit: This must be set to the bit to disable (same bit that was
 178   previously registered via enable_bit).
 179
 180 + disable_addr: This must be set to the address to disable (same address that was
 181   previously registered via enable_addr).
 182
 183 **NOTE:** Events are automatically unregistered when execve() is invoked. During
 184 fork() the registered events will be retained and must be unregistered manually
 185 in each process if wanted.
 186
 187 Status
 188 ------
 189 When tools attach/record user based events the status of the event is updated
 190 in realtime. This allows user programs to only incur the cost of the write() or
 191 writev() calls when something is actively attached to the event.
 192
 193 The kernel will update the specified bit that was registered for the event as
 194 tools attach/detach from the event. User programs simply check if the bit is set
 195 to see if something is attached or not.
 196
 197 Administrators can easily check the status of all registered events by reading
 198 the user_events_status file directly via a terminal. The output is as follows::
 199
 200   Name [# Comments]
 201   ...
 202
 203   Active: ActiveCount
 204   Busy: BusyCount
 205
 206 For example, on a system that has a single event the output looks like this::
 207
 208   test
 209
 210   Active: 1
 211   Busy: 0
 212
 213 If a user enables the user event via ftrace, the output would change to this::
 214
 215   test # Used by ftrace
 216
 217   Active: 1
 218   Busy: 1
 219
 220 Writing Data
 221 ------------
 222 After registering an event the same fd that was used to register can be used
 223 to write an entry for that event. The write_index returned must be at the start
 224 of the data, then the remaining data is treated as the payload of the event.
 225
 226 For example, if write_index returned was 1 and I wanted to write out an int
 227 payload of the event. Then the data would have to be 8 bytes (2 ints) in size,
 228 with the first 4 bytes being equal to 1 and the last 4 bytes being equal to the
 229 value I want as the payload.
 230
 231 In memory this would look like this::
 232
 233   int index;
 234   int payload;
 235
 236 User programs might have well known structs that they wish to use to emit out
 237 as payloads. In those cases writev() can be used, with the first vector being
 238 the index and the following vector(s) being the actual event payload.
 239
 240 For example, if I have a struct like this::
 241
 242   struct payload {
 243         int src;
 244         int dst;
 245         int flags;
 246   } __attribute__((__packed__));
 247
 248 It's advised for user programs to do the following::
 249
 250   struct iovec io[2];
 251   struct payload e;
 252
 253   io[0].iov_base = &write_index;
 254   io[0].iov_len = sizeof(write_index);
 255   io[1].iov_base = &e;
 256   io[1].iov_len = sizeof(e);
 257
 258   writev(fd, (const struct iovec*)io, 2);
 259
 260 **NOTE:** *The write_index is not emitted out into the trace being recorded.*
 261
 262 Example Code
 263 ------------
 264 See sample code in samples/user_events.