2 id: tracepoint-provider
5 Before jumping into defining tracepoints and inserting
6 them into the application source code, you must understand what a
7 _tracepoint provider_ is.
9 For the sake of this guide, consider the following two files:
14 #undef TRACEPOINT_PROVIDER
15 #define TRACEPOINT_PROVIDER my_provider
17 #undef TRACEPOINT_INCLUDE
18 #define TRACEPOINT_INCLUDE "./tp.h"
20 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
23 #include <lttng/tracepoint.h>
33 ctf_string(my_string_field, my_string_arg)
34 ctf_integer(int, my_integer_field, my_integer_arg)
45 ctf_integer(int, some_field, my_int)
51 #include <lttng/tracepoint-event.h>
57 #define TRACEPOINT_CREATE_PROBES
62 The two files above are defining a _tracepoint provider_. A tracepoint
63 provider is some sort of namespace for _tracepoint definitions_. Tracepoint
64 definitions are written above with the `TRACEPOINT_EVENT()` macro, and allow
65 eventual `tracepoint()` calls respecting their definitions to be inserted
66 into the user application's C source code (we explore this in a
69 Many tracepoint definitions may be part of the same tracepoint provider
70 and many tracepoint providers may coexist in a user space application. A
71 tracepoint provider is packaged either:
73 * directly into an existing user application's C source file
78 The two files above, `tp.h` and `tp.c`, show a typical template for
79 writing a tracepoint provider. LTTng-UST was designed so that two
80 tracepoint providers should not be defined in the same header file.
82 We will now go through the various parts of the above files and
83 give them a meaning. As you may have noticed, the LTTng-UST API for
84 C/C++ applications is some preprocessor sorcery. The LTTng-UST macros
85 used in your application and those in the LTTng-UST headers are
86 combined to produce actual source code needed to make tracing possible
89 Let's start with the header file, `tp.h`. It begins with
92 #undef TRACEPOINT_PROVIDER
93 #define TRACEPOINT_PROVIDER my_provider
96 `TRACEPOINT_PROVIDER` defines the name of the provider to which the
97 following tracepoint definitions belong. It is used internally by
98 LTTng-UST headers and _must_ be defined. Since `TRACEPOINT_PROVIDER`
99 could have been defined by another header file also included by the same
100 C source file, the best practice is to undefine it first.
103 <p><span class="t">Note:</span>Names in LTTng-UST follow the C
104 <em>identifier</em> syntax (starting with a letter and containing either
105 letters, numbers or underscores); they are <em>not</em> C strings
106 (not surrounded by double quotes). This is because LTTng-UST macros
107 use those identifier-like strings to create symbols (named types and
111 The tracepoint provider is a group of tracepoint definitions; its chosen
112 name should reflect this. A hierarchy like Java packages is recommended,
113 using underscores instead of dots, for example,
114 `org_company_project_component`.
116 Next is `TRACEPOINT_INCLUDE`:
119 #undef TRACEPOINT_INCLUDE
120 #define TRACEPOINT_INCLUDE "./tp.h"
123 This little bit of instrospection is needed by LTTng-UST to include
124 your header at various predefined places.
126 Include guard follows:
129 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
133 Add these precompiler conditionals to ensure the tracepoint event
134 generation can include this file more than once.
136 The `TRACEPOINT_EVENT()` macro is defined in a LTTng-UST header file which
140 #include <lttng/tracepoint.h>
143 This also allows the application to use the `tracepoint()` macro.
145 Next is a list of `TRACEPOINT_EVENT()` macro calls which create the
146 actual tracepoint definitions. We skip this for the moment and
147 come back to how to use `TRACEPOINT_EVENT()`
148 [in a later section](#doc-defining-tracepoints). Just pay attention to
149 the first argument: it's always the name of the tracepoint provider
150 being defined in this header file.
152 End of include guard:
158 Finally, include `<lttng/tracepoint-event.h>` to expand the macros:
161 #include <lttng/tracepoint-event.h>
164 That's it for `tp.h`. Of course, this is only a header file; it must be
165 included in some C source file to actually use it. This is the job of
169 #define TRACEPOINT_CREATE_PROBES
174 When `TRACEPOINT_CREATE_PROBES` is defined, the macros used in `tp.h`,
175 which is included just after, actually create the source code for
176 LTTng-UST probes (global data structures and functions) out of your
177 tracepoint definitions. How exactly this is done is out of this text's scope.
178 `TRACEPOINT_CREATE_PROBES` is discussed further
179 in [Building/linking tracepoint providers and the user application](#doc-building-tracepoint-providers-and-user-application).
181 You could include other header files like `tp.h` here to create the probes
182 of different tracepoint providers, for example:
185 #define TRACEPOINT_CREATE_PROBES
191 The rule is: probes of a given tracepoint provider
192 must be created in exactly one source file. This source file could be one
193 of your project's; it doesn't have to be on its own like `tp.c`, although
194 [a later section](#doc-building-tracepoint-providers-and-user-application)
195 shows that doing so allows packaging the tracepoint providers
196 independently and keep them out of your application, also making it
197 possible to reuse them between projects.
199 The following sections explain how to define tracepoints, how to use the
200 `tracepoint()` macro to instrument your user space C application and how
201 to build/link tracepoint providers and your application with LTTng-UST