aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorTheodore Ts'o <tytso@mit.edu>2009-04-11 15:51:18 -0400
committerIngo Molnar <mingo@elte.hu>2009-04-12 08:57:12 -0400
commitabd41443ac76d3e9c29a8c1d9e9a3312306cc55e (patch)
treec05bb3aed407669a3314338182f4d03cf906692e /Documentation
parent56c49951747f250d8398582509e02ae5ce1d36d1 (diff)
tracing: Document the event tracing system
Signed-off-by: "Theodore Ts'o" <tytso@mit.edu> Cc: Theodore Ts'o <tytso@mit.edu> Cc: Steven Rostedt <rostedt@goodmis.org> LKML-Reference: <1239479479-2603-3-git-send-email-tytso@mit.edu> Signed-off-by: Ingo Molnar <mingo@elte.hu>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/trace/events.txt135
1 files changed, 135 insertions, 0 deletions
diff --git a/Documentation/trace/events.txt b/Documentation/trace/events.txt
new file mode 100644
index 000000000000..abdee664c0f6
--- /dev/null
+++ b/Documentation/trace/events.txt
@@ -0,0 +1,135 @@
1 Event Tracing
2
3 Documentation written by Theodore Ts'o
4
5Introduction
6============
7
8Tracepoints (see Documentation/trace/tracepoints.txt) can be used
9without creating custom kernel modules to register probe functions
10using the event tracing infrastructure.
11
12Not all tracepoints can be traced using the event tracing system;
13the kernel developer must provide code snippets which define how the
14tracing information is saved into the tracing buffer, and how the
15the tracing information should be printed.
16
17Using Event Tracing
18===================
19
20The events which are available for tracing can be found in the file
21/sys/kernel/debug/tracing/available_events.
22
23To enable a particular event, such as 'sched_wakeup', simply echo it
24to /sys/debug/tracing/set_event. For example:
25
26 # echo sched_wakeup > /sys/kernel/debug/tracing/set_event
27
28[ Note: events can also be enabled/disabled via the 'enabled' toggle
29 found in the /sys/kernel/tracing/events/ hierarchy of directories. ]
30
31To disable an event, echo the event name to the set_event file prefixed
32with an exclamation point:
33
34 # echo '!sched_wakeup' >> /sys/kernel/debug/tracing/set_event
35
36To disable events, echo an empty line to the set_event file:
37
38 # echo > /sys/kernel/debug/tracing/set_event
39
40The events are organized into subsystems, such as ext4, irq, sched,
41etc., and a full event name looks like this: <subsystem>:<event>. The
42subsystem name is optional, but it is displayed in the available_events
43file. All of the events in a subsystem can be specified via the syntax
44"<subsystem>:*"; for example, to enable all irq events, you can use the
45command:
46
47 # echo 'irq:*' > /sys/kernel/debug/tracing/set_event
48
49Defining an event-enabled tracepoint
50------------------------------------
51
52A kernel developer which wishes to define an event-enabled tracepoint
53must declare the tracepoint using TRACE_EVENT instead of DECLARE_TRACE.
54This is done via two header files in include/trace. For example, to
55event-enable the jbd2 subsystem, we must create two files,
56include/trace/jbd2.h and include/trace/jbd2_event_types.h. The
57include/trace/jbd2.h file should be included by kernel source files that
58will have a tracepoint inserted, and might look like this:
59
60#ifndef _TRACE_JBD2_H
61#define _TRACE_JBD2_H
62
63#include <linux/jbd2.h>
64#include <linux/tracepoint.h>
65
66#include <trace/jbd2_event_types.h>
67
68#endif
69
70In a file that utilizes a jbd2 tracepoint, this header file would be
71included. Note that you still have to use DEFINE_TRACE(). So for
72example, if fs/jbd2/commit.c planned to use the jbd2_start_commit
73tracepoint, it would have the following near the beginning of the file:
74
75#include <trace/jbd2.h>
76
77DEFINE_TRACE(jbd2_start_commit);
78
79Then in the function that would call the tracepoint, it would call the
80tracepoint function. (For more information, please see the tracepoint
81documentation in Documentation/trace/tracepoints.txt):
82
83 trace_jbd2_start_commit(journal, commit_transaction);
84
85The code snippets which allow jbd2_start_commit to be an event-enabled
86tracepoint are placed in the file include/trace/jbd2_event_types.h:
87
88/* use <trace/jbd2.h> instead */
89#ifndef TRACE_EVENT
90# error Do not include this file directly.
91# error Unless you know what you are doing.
92#endif
93
94#undef TRACE_SYSTEM
95#define TRACE_SYSTEM jbd2
96
97#include <linux/jbd2.h>
98
99TRACE_EVENT(jbd2_start_commit,
100 TP_PROTO(journal_t *journal, transaction_t *commit_transaction),
101 TP_ARGS(journal, commit_transaction),
102 TP_STRUCT__entry(
103 __array( char, devname, BDEVNAME_SIZE+24 )
104 __field( int, transaction )
105 ),
106 TP_fast_assign(
107 memcpy(__entry->devname, journal->j_devname, BDEVNAME_SIZE+24);
108 __entry->transaction = commit_transaction->t_tid;
109 ),
110 TP_printk("dev %s transaction %d",
111 __entry->devname, __entry->transaction)
112);
113
114The TP_PROTO and TP_ARGS are unchanged from DECLARE_TRACE. The new
115arguments to TRACE_EVENT are TP_STRUCT__entry, TP_fast_assign, and
116TP_printk.
117
118TP_STRUCT__entry defines the data structure which will be stored in the
119trace buffer. Normally, fields in __entry will be arrays or simple
120types. It is possible to place data structures in __entry --- however,
121pointers in the data structure can not be trusted, since they will be
122accessed sometime later by TP_printk, and if the data structure contains
123fields that will not or cannot be used by TP_printk, this will waste
124space in the trace buffer. In general, data structures should be
125avoided, unless they do only contain non-pointer types and all of the
126fields will be used by TP_printk.
127
128TP_fast_assign defines the code snippet which saves information into the
129__entry data structure, using the passed-in arguments defined in
130TP_PROTO and TP_ARGS.
131
132Finally, TP_printk will print the __entry data structure. At the time
133when the code snippet defined by TP_printk is executed, it will not have
134access to the TP_ARGS arguments; it can only use the information saved
135in the __entry data structure.