2 id: tracing-your-own-user-application
5 The previous section helped you create a trace out of Linux kernel events.
6 This section steps you through a simple example showing you how to trace
7 a _Hello world_ program written in C.
9 Make sure the LTTng-tools and LTTng-UST packages
10 [are installed](#doc-installing-lttng).
12 Tracing is just like having `printf()` calls at specific locations of
13 your source code, albeit LTTng is much more faster and flexible than
14 `printf()`. In the LTTng realm, **`tracepoint()`** is analogous to
17 Unlike `printf()`, though, `tracepoint()` does not use a format string to
18 know the types of its arguments: the formats of all tracepoints must be
19 defined before using them. So before even writing our _Hello world_ program,
20 we need to define the format of our tracepoint. This is done by creating a
21 **tracepoint provider**, which consists of a tracepoint provider header
22 (`.h` file) and a tracepoint provider definition (`.c` file).
24 The tracepoint provider header contains some boilerplate as well as a
25 list of tracepoint definitions and other optional definition entries
26 which we skip for this quickstart. Each tracepoint is defined using the
27 `TRACEPOINT_EVENT()` macro. For each tracepoint, you must provide:
29 * a **provider name**, which is the "scope" or namespace of this
30 tracepoint (this usually includes the company and project names)
31 * a **tracepoint name**
32 * a **list of arguments** for the eventual `tracepoint()` call, each
36 * a **list of fields**, which correspond to the actual fields of the
37 recorded events for this tracepoint
39 Here's an example of a simple tracepoint provider header with two
40 arguments: an integer and a string:
43 #undef TRACEPOINT_PROVIDER
44 #define TRACEPOINT_PROVIDER hello_world
46 #undef TRACEPOINT_INCLUDE
47 #define TRACEPOINT_INCLUDE "./tp.h"
49 #if !defined(_HELLO_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
52 #include <lttng/tracepoint.h>
62 ctf_string(my_string_field, my_string_arg)
63 ctf_integer(int, my_integer_field, my_integer_arg)
67 #endif /* _HELLO_TP_H */
69 #include <lttng/tracepoint-event.h>
72 The exact syntax is well explained in the
73 [C application](#doc-c-application) instrumentation guide of the
74 [Using LTTng](#doc-using-lttng) chapter, as well as in the
75 <a href="/man/3/lttng-ust" class="ext">LTTng-UST man page</a>.
77 Save the above snippet as `hello-tp.h`.
79 Write the tracepoint provider definition as `hello-tp.c`:
82 #define TRACEPOINT_CREATE_PROBES
83 #define TRACEPOINT_DEFINE
88 Create the tracepoint provider:
94 Now, by including `hello-tp.h` in your own application, you may use the
95 tracepoint defined above by properly refering to it when calling
100 #include "hello-tp.h"
102 int main(int argc, char *argv[])
106 puts("Hello, World!\nPress Enter to continue...");
109 * The following getchar() call is only placed here for the purpose
110 * of this demonstration, for pausing the application in order for
111 * you to have time to list its events. It's not needed otherwise.
116 * A tracepoint() call. Arguments, as defined in hello-tp.h:
118 * 1st: provider name (always)
119 * 2nd: tracepoint name (always)
120 * 3rd: my_integer_arg (first user-defined argument)
121 * 4th: my_string_arg (second user-defined argument)
123 * Notice the provider and tracepoint names are NOT strings;
124 * they are in fact parts of variables created by macros in
127 tracepoint(hello_world, my_first_tracepoint, 23, "hi there!");
129 for (x = 0; x < argc; ++x) {
130 tracepoint(hello_world, my_first_tracepoint, x, argv[x]);
133 puts("Quitting now!");
135 tracepoint(hello_world, my_first_tracepoint, x * x, "x^2");
141 Save this as `hello.c`, next to `hello-tp.c`.
143 Notice `hello-tp.h`, the tracepoint provider header, is included
146 You are now ready to compile the application with LTTng-UST support:
150 gcc -o hello hello.o hello-tp.o -llttng-ust -ldl</strong>
153 Here's the whole build process:
156 <img src="/images/docs26/ust-flow.png" alt="User space tracing's build process">
160 [Tracing the Linux kernel](#doc-tracing-the-linux-kernel) tutorial, the
161 following steps should look familiar.
163 First, run the application with a few arguments:
166 ./hello world and beyond
173 Press Enter to continue...
176 Use the `lttng` tool to list all available user space events:
179 lttng list --userspace
182 You should see the `hello_world:my_first_tracepoint` tracepoint listed
183 under the `./hello` process.
185 Create a tracing session:
191 Enable the `hello_world:my_first_tracepoint` tracepoint:
194 lttng enable-event --userspace hello_world:my_first_tracepoint
203 Go back to the running `hello` application and press Enter. All `tracepoint()`
204 calls are executed and the program finally exits.
212 Done! You may use `lttng view` to list the recorded events. This command
214 <a href="http://diamon.org/babeltrace" class="ext"><code>babeltrace</code></a>
215 in the background, if it's installed:
221 should output something like:
224 [18:10:27.684304496] (+?.?????????) hostname hello_world:my_first_tracepoint: { cpu_id = 0 }, { my_string_field = "hi there!", my_integer_field = 23 }
225 [18:10:27.684338440] (+0.000033944) hostname hello_world:my_first_tracepoint: { cpu_id = 0 }, { my_string_field = "./hello", my_integer_field = 0 }
226 [18:10:27.684340692] (+0.000002252) hostname hello_world:my_first_tracepoint: { cpu_id = 0 }, { my_string_field = "world", my_integer_field = 1 }
227 [18:10:27.684342616] (+0.000001924) hostname hello_world:my_first_tracepoint: { cpu_id = 0 }, { my_string_field = "and", my_integer_field = 2 }
228 [18:10:27.684343518] (+0.000000902) hostname hello_world:my_first_tracepoint: { cpu_id = 0 }, { my_string_field = "beyond", my_integer_field = 3 }
229 [18:10:27.684357978] (+0.000014460) hostname hello_world:my_first_tracepoint: { cpu_id = 0 }, { my_string_field = "x^2", my_integer_field = 16 }
232 When you're done, you may destroy the tracing session, which does _not_
233 destroy the generated trace files, leaving them available for further
240 The next section presents other alternatives to view and analyze your