Documentation/trace/events.txt

   1                              Event Tracing
   2
   3                 Documentation written by Theodore Ts'o
   4                         Updated by Li Zefan
   5
   6 1. Introduction
   7 ===============
   8
   9 Tracepoints (see Documentation/trace/tracepoints.txt) can be used
  10 without creating custom kernel modules to register probe functions
  11 using the event tracing infrastructure.
  12
  13 Not all tracepoints can be traced using the event tracing system;
  14 the kernel developer must provide code snippets which define how the
  15 tracing information is saved into the tracing buffer, and how the
  16 tracing information should be printed.
  17
  18 2. Using Event Tracing
  19 ======================
  20
  21 2.1 Via the 'set_event' interface
  22 ---------------------------------
  23
  24 The events which are available for tracing can be found in the file
  25 /sys/kernel/debug/tracing/available_events.
  26
  27 To enable a particular event, such as 'sched_wakeup', simply echo it
  28 to /sys/kernel/debug/tracing/set_event. For example:
  29
  30         # echo sched_wakeup >> /sys/kernel/debug/tracing/set_event
  31
  32 [ Note: '>>' is necessary, otherwise it will firstly disable
  33   all the events. ]
  34
  35 To disable an event, echo the event name to the set_event file prefixed
  36 with an exclamation point:
  37
  38         # echo '!sched_wakeup' >> /sys/kernel/debug/tracing/set_event
  39
  40 To disable all events, echo an empty line to the set_event file:
  41
  42         # echo > /sys/kernel/debug/tracing/set_event
  43
  44 To enable all events, echo '*:*' or '*:' to the set_event file:
  45
  46         # echo *:* > /sys/kernel/debug/tracing/set_event
  47
  48 The events are organized into subsystems, such as ext4, irq, sched,
  49 etc., and a full event name looks like this: <subsystem>:<event>.  The
  50 subsystem name is optional, but it is displayed in the available_events
  51 file.  All of the events in a subsystem can be specified via the syntax
  52 "<subsystem>:*"; for example, to enable all irq events, you can use the
  53 command:
  54
  55         # echo 'irq:*' > /sys/kernel/debug/tracing/set_event
  56
  57 2.2 Via the 'enable' toggle
  58 ---------------------------
  59
  60 The events available are also listed in /sys/kernel/debug/tracing/events/ hierarchy
  61 of directories.
  62
  63 To enable event 'sched_wakeup':
  64
  65         # echo 1 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable
  66
  67 To disable it:
  68
  69         # echo 0 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable
  70
  71 To enable all events in sched subsystem:
  72
  73         # echo 1 > /sys/kernel/debug/tracing/events/sched/enable
  74
  75 To eanble all events:
  76
  77         # echo 1 > /sys/kernel/debug/tracing/events/enable
  78
  79 When reading one of these enable files, there are four results:
  80
  81  0 - all events this file affects are disabled
  82  1 - all events this file affects are enabled
  83  X - there is a mixture of events enabled and disabled
  84  ? - this file does not affect any event
  85
  86 2.3 Boot option
  87 ---------------
  88
  89 In order to facilitate early boot debugging, use boot option:
  90
  91         trace_event=[event-list]
  92
  93 The format of this boot option is the same as described in section 2.1.
  94
  95 3. Defining an event-enabled tracepoint
  96 =======================================
  97
  98 See The example provided in samples/trace_events
  99