2 id: defining-tracepoints
5 As written in [Tracepoint provider](#doc-tracepoint-provider),
6 tracepoints are defined using the
7 `TRACEPOINT_EVENT()` macro. Each tracepoint, when called using the
8 `tracepoint()` macro in the actual application's source code, generates
9 a specific event type with its own fields.
11 Let's have another look at the example above, with a few added comments:
15 /* tracepoint provider name */
18 /* tracepoint/event name */
21 /* list of tracepoint arguments */
27 /* list of fields of eventual event */
29 ctf_string(my_string_field, my_string_arg)
30 ctf_integer(int, my_integer_field, my_integer_arg)
35 The tracepoint provider name must match the name of the tracepoint
36 provider in which this tracepoint is defined
37 (see [Tracepoint provider](#doc-tracepoint-provider)). In other words,
38 always use the same string as the value of `TRACEPOINT_PROVIDER` above.
40 The tracepoint name becomes the event name once events are recorded
41 by the LTTng-UST tracer. It must follow the tracepoint provider name
42 syntax: start with a letter and contain either letters, numbers or
43 underscores. Two tracepoints under the same provider cannot have the
44 same name, i.e. you cannot overload a tracepoint like you would
45 overload functions and methods in C++/Java.
48 <p><span class="t">Note:</span>The concatenation of the tracepoint
49 provider name and the tracepoint name cannot exceed 254 characters. If
50 it does, the instrumented application compiles and runs, but LTTng
51 issues multiple warnings and you could experience serious problems.</p>
54 The list of tracepoint arguments gives this tracepoint its signature:
55 see it like the declaration of a C function. The format of `TP_ARGS()`
56 arguments is: C type, then argument name; repeat as needed, up to ten
57 times. For example, if we were to replicate the signature of C standard
58 library's `fseek()`, the `TP_ARGS()` part would look like:
68 Of course, you need to include appropriate header files before
69 the `TRACEPOINT_EVENT()` macro calls if any argument has a complex type.
71 `TP_ARGS()` may not be omitted, but may be empty. `TP_ARGS(void)` is
74 The list of fields is where the fun really begins. The fields defined
75 in this list are the fields of the events generated by the execution
76 of this tracepoint. Each tracepoint field definition has a C
77 _argument expression_ which is evaluated when the execution reaches
78 the tracepoint. Tracepoint arguments _may be_ used freely in those
79 argument expressions, but they _don't_ have to.
81 There are several types of tracepoint fields available. The macros to
82 define them are given and explained in the
83 [LTTng-UST library reference](#doc-liblttng-ust-tp-fields) section.
85 Field names must follow the standard C identifier syntax: letter, then
86 optional sequence of letters, numbers or underscores. Each field must have
89 Those `ctf_*()` macros are added to the `TP_FIELDS()` part of
90 `TRACEPOINT_EVENT()`. Note that they are not delimited by commas.
91 `TP_FIELDS()` may be empty, but the `TP_FIELDS(void)` form is _not_
94 The following snippet shows how argument expressions may be used in
95 tracepoint fields and how they may refer freely to tracepoint arguments.
99 #include <sys/types.h>
100 #include <sys/stat.h>
112 /* simple integer field with constant value */
114 int, /* field C type */
115 my_constant_field, /* field name */
116 23 + 17 /* argument expression */
119 /* my_int_arg tracepoint argument */
126 /* my_int_arg squared */
130 my_int_arg * my_int_arg
133 /* sum of first 4 characters of my_str_arg */
137 my_str_arg[0] + my_str_arg[1] +
138 my_str_arg[2] + my_str_arg[3]
141 /* my_str_arg as string field */
143 my_str_arg_field, /* field name */
144 my_str_arg /* argument expression */
147 /* st_size member of st tracepoint argument, hexadecimal */
149 off_t, /* field C type */
150 size_field, /* field name */
151 st->st_size /* argument expression */
154 /* st_size member of st tracepoint argument, as double */
156 double, /* field C type */
157 size_dbl_field, /* field name */
158 (double) st->st_size /* argument expression */
161 /* half of my_str_arg string as text sequence */
163 char, /* element C type */
164 half_my_str_arg_field, /* field name */
165 my_str_arg, /* argument expression */
166 size_t, /* length expression C type */
167 strlen(my_str_arg) / 2 /* length expression */
173 As you can see, having a custom argument expression for each field
174 makes tracepoints very flexible for tracing a user space C application.
175 This tracepoint definition is reused later in this guide, when
176 actually using tracepoints in a user space application.