manpage -> man pages

[lttng-docs.git] / contents / getting-started / tracing-your-own-user-application.md

---
id: tracing-your-own-user-application
---

The previous section helped you create a trace out of Linux kernel events.
This section steps you through a simple example showing you how to trace
a _Hello world_ program written in C.

Make sure LTTng-tools and LTTng-UST packages
[are installed](#doc-installing-lttng).

Tracing is just like having `printf()` calls at specific locations of
your source code, albeit LTTng is much more faster and flexible than
`printf()`. In the LTTng realm, **`tracepoint()`** is analogous to
`printf()`.

Unlike `printf()`, though, `tracepoint()` does not use a format string to
know the types of its arguments: the formats of all tracepoints must be
defined before using them. So before even writing our _Hello world_ program,
we need to define the format of our tracepoint. This is done by writing a
**template file**, with a name usually ending with the `.tp` extension (for **t**race**p**oint),
which the `lttng-gen-tp` tool (shipped with LTTng-UST) uses to generate
an object file (along with a `.c` file) and a header to be included in our application source code.

Here's the whole flow:

<div class="img img-80">
    <object data="/images/docs26/lttng-lttng-gen-tp.svg" type="image/svg+xml">
        <img src="/images/docs26/lttng-lttng-gen-tp.svg">
    </object>
</div>

The template file format is a list of tracepoint definitions
and other optional definition entries which we skip for
this quickstart. Each tracepoint is defined using the
`TRACEPOINT_EVENT()` macro. For each tracepoint, you must provide:

  * a **provider name**, which is the "scope" of this tracepoint (this usually
    includes the company and project names)
  * a **tracepoint name**
  * a **list of arguments** for the eventual `tracepoint()` call, each item being:
    * the argument C type
    * the argument name
  * a **list of fields**, which correspond to the actual fields of the
    recorded events for this tracepoint

Here's a simple tracepoint definition example with two arguments: an integer
and a string:

~~~ c
TRACEPOINT_EVENT(
    hello_world,
    my_first_tracepoint,
    TP_ARGS(
        int, my_integer_arg,
        char*, my_string_arg
    ),
    TP_FIELDS(
        ctf_string(my_string_field, my_string_arg)
        ctf_integer(int, my_integer_field, my_integer_arg)
    )
)
~~~

The exact syntax is well explained in the
[C application](#doc-c-application) instrumenting guide of the
[Using LTTng](#doc-using-lttng) chapter, as well as in the
<a href="/man/3/lttng-ust" class="ext">LTTng-UST man page</a>.

Save the above snippet as `hello-tp.tp` and run:

<pre class="term">
lttng-gen-tp hello-tp.tp
</pre>

The following files are created next to `hello-tp.tp`:

  * `hello-tp.c`
  * `hello-tp.o`
  * `hello-tp.h`

`hello-tp.o` is the compiled object file of `hello-tp.c`.

Now, by including `hello-tp.h` in your own application, you may use the
tracepoint defined above by properly refering to it when calling
`tracepoint()`:

~~~ c
#include <stdio.h>
#include "hello-tp.h"

int main(int argc, char* argv[])
{
    int x;

    puts("Hello, World!\nPress Enter to continue...");

    /* The following getchar() call is only placed here for the purpose
     * of this demonstration, for pausing the application in order for
     * you to have time to list its events. It's not needed otherwise.
     */
    getchar();

    /* A tracepoint() call. Arguments, as defined in hello-tp.tp:
     *
     *     1st: provider name (always)
     *     2nd: tracepoint name (always)
     *     3rd: my_integer_arg (first user-defined argument)
     *     4th: my_string_arg (second user-defined argument)
     *
     * Notice the provider and tracepoint names are NOT strings;
     * they are in fact parts of variables created by macros in
     * hello-tp.h.
     */
    tracepoint(hello_world, my_first_tracepoint, 23, "hi there!");

    for (x = 0; x < argc; ++x) {
        tracepoint(hello_world, my_first_tracepoint, x, argv[x]);
    }

    puts("Quitting now!");

    tracepoint(hello_world, my_first_tracepoint, x * x, "x^2");

    return 0;
}
~~~

Save this as `hello.c`, next to `hello-tp.tp`.

Notice `hello-tp.h`, the header file generated by `lttng-gen-tp` from
our template file `hello-tp.tp`, is included by `hello.c`.

You are now ready to compile the application with LTTng-UST support:

<pre class="term">
gcc -o hello hello.c <strong>hello-tp.o -llttng-ust -ldl</strong>
</pre>

If you followed the
[Tracing the Linux kernel](#doc-tracing-the-linux-kernel) section, the
following steps should look familiar.

First, run the application with a few arguments:

<pre class="term">
./hello world and beyond
</pre>

You should see

~~~ text
Hello, World!
Press Enter to continue...
~~~

Use the `lttng` tool to list all available user space events:

<pre class="term">
lttng list --userspace
</pre>

You should see the `hello_world:my_first_tracepoint` tracepoint listed
under the `./hello` process.

Create a tracing session:

<pre class="term">
lttng create my-userspace-session
</pre>

Enable the `hello_world:my_first_tracepoint` tracepoint:

<pre class="term">
lttng enable-event --userspace hello_world:my_first_tracepoint
</pre>

Start tracing:

<pre class="term">
lttng start
</pre>

Go back to the running `hello` application and press Enter. All `tracepoint()`
calls are executed and the program finally exits.

Stop tracing:

<pre class="term">
lttng stop
</pre>

Done! You may use `lttng view` to list the recorded events. This command
starts
<a href="http://www.efficios.com/babeltrace" class="ext"><code>babeltrace</code></a>
in the background, if it is installed:

<pre class="term">
lttng view
</pre>

should output something like:

~~~ text
[18:10:27.684304496] (+?.?????????) hostname hello_world:my_first_tracepoint: { cpu_id = 0 }, { my_string_field = "hi there!", my_integer_field = 23 }
[18:10:27.684338440] (+0.000033944) hostname hello_world:my_first_tracepoint: { cpu_id = 0 }, { my_string_field = "./hello", my_integer_field = 0 }
[18:10:27.684340692] (+0.000002252) hostname hello_world:my_first_tracepoint: { cpu_id = 0 }, { my_string_field = "world", my_integer_field = 1 }
[18:10:27.684342616] (+0.000001924) hostname hello_world:my_first_tracepoint: { cpu_id = 0 }, { my_string_field = "and", my_integer_field = 2 }
[18:10:27.684343518] (+0.000000902) hostname hello_world:my_first_tracepoint: { cpu_id = 0 }, { my_string_field = "beyond", my_integer_field = 3 }
[18:10:27.684357978] (+0.000014460) hostname hello_world:my_first_tracepoint: { cpu_id = 0 }, { my_string_field = "x^2", my_integer_field = 16 }
~~~

When you're done, you may destroy the tracing session, which does _not_
destroy the generated trace files, leaving them available for further
analysis:

<pre class="term">
lttng destroy my-userspace-session
</pre>

The next section presents other alternatives to view and analyze your
LTTng traces.