Merge remote-tracking branch 'gh-tuxology/patch-1'

[lttng-docs.git] / contents / using-lttng / instrumenting / c-application / probing-the-application-source-code.md

---
id: probing-the-application-source-code
---

Once tracepoints are properly defined within a tracepoint provider,
they may be inserted into the user application to be instrumented
using the `tracepoint()` macro. Its first argument is the tracepoint
provider name and its second is the tracepoint name. The next, optional
arguments are defined by the `TP_ARGS()` part of the definition of
the tracepoint to use.

As an example, let us again take the following tracepoint definition:

~~~ c
TRACEPOINT_EVENT(
    /* tracepoint provider name */
    my_provider,

    /* tracepoint/event name */
    my_first_tracepoint,

    /* list of tracepoint arguments */
    TP_ARGS(
        int, my_integer_arg,
        char*, my_string_arg
    ),

    /* list of fields of eventual event  */
    TP_FIELDS(
        ctf_string(my_string_field, my_string_arg)
        ctf_integer(int, my_integer_field, my_integer_arg)
    )
)
~~~

Assuming this is part of a file named `tp.h` which defines the tracepoint
provider and which is included by `tp.c`, here's a complete C application
calling this tracepoint (multiple times):

~~~ c
#define TRACEPOINT_DEFINE
#include "tp.h"

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

    tracepoint(my_provider, my_first_tracepoint, 23, "Hello, World!");

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

    return 0;
}
~~~

`TRACEPOINT_DEFINE` must be defined into exactly one translation unit (C
source file) of the user application, before including the tracepoint provider
header file. `TRACEPOINT_DEFINE` is discussed further in
[Building/linking tracepoint providers and the user application](#doc-building-tracepoint-providers-and-user-application).

As another example, remember this definition we wrote in a previous
section (comments are stripped):

~~~ c
/* for struct stat */
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>

TRACEPOINT_EVENT(
    my_provider,
    my_tracepoint,
    TP_ARGS(
        int, my_int_arg,
        char*, my_str_arg,
        struct stat*, st
    ),
    TP_FIELDS(
        ctf_integer(int, my_constant_field, 23 + 17)
        ctf_integer(int, my_int_arg_field, my_int_arg)
        ctf_integer(int, my_int_arg_field2, my_int_arg * my_int_arg)
        ctf_integer(int, sum4_field, my_str_arg[0] + my_str_arg[1] +
                                     my_str_arg[2] + my_str_arg[3])
        ctf_string(my_str_arg_field, my_str_arg)
        ctf_integer_hex(off_t, size_field, st->st_size)
        ctf_float(double, size_dbl_field, (double) st->st_size)
        ctf_sequence_text(char, half_my_str_arg_field, my_str_arg,
                          size_t, strlen(my_str_arg) / 2)
    )
)
~~~

Here's an example of calling it:

~~~ c
#define TRACEPOINT_DEFINE
#include "tp.h"

int main(void)
{
    struct stat s;

    stat("/etc/fstab", &s);

    tracepoint(my_provider, my_tracepoint, 23, "Hello, World!", &s);

    return 0;
}
~~~

When viewing the trace, assuming the file size of `/etc/fstab` is
301&nbsp;bytes, the event generated by the execution of this tracepoint
should have the following fields, in this order:

~~~ text
my_constant_field           40
my_int_arg_field            23
my_int_arg_field2           529
sum4_field                  389
my_str_arg_field            "Hello, World!"
size_field                  0x12d
size_dbl_field              301.0
half_my_str_arg_field       "Hello,"
~~~