contents/using-lttng/instrumenting/c-application/probing-the-application-source-code.md

   1 ---
   2 id: probing-the-application-source-code
   3 ---
   4
   5 Once tracepoints are properly defined within a tracepoint provider,
   6 they may be inserted into the user application to be instrumented
   7 using the `tracepoint()` macro. Its first argument is the tracepoint
   8 provider name and its second is the tracepoint name. The next, optional
   9 arguments are defined by the `TP_ARGS()` part of the definition of
  10 the tracepoint to use.
  11
  12 As an example, let us again take the following tracepoint definition:
  13
  14 ~~~ c
  15 TRACEPOINT_EVENT(
  16     /* tracepoint provider name */
  17     my_provider,
  18
  19     /* tracepoint/event name */
  20     my_first_tracepoint,
  21
  22     /* list of tracepoint arguments */
  23     TP_ARGS(
  24         int, my_integer_arg,
  25         char*, my_string_arg
  26     ),
  27
  28     /* list of fields of eventual event  */
  29     TP_FIELDS(
  30         ctf_string(my_string_field, my_string_arg)
  31         ctf_integer(int, my_integer_field, my_integer_arg)
  32     )
  33 )
  34 ~~~
  35
  36 Assuming this is part of a file named `tp.h` which defines the tracepoint
  37 provider and which is included by `tp.c`, here's a complete C application
  38 calling this tracepoint (multiple times):
  39
  40 ~~~ c
  41 #define TRACEPOINT_DEFINE
  42 #include "tp.h"
  43
  44 int main(int argc, char* argv[])
  45 {
  46     int i;
  47
  48     tracepoint(my_provider, my_first_tracepoint, 23, "Hello, World!");
  49
  50     for (i = 0; i < argc; ++i) {
  51         tracepoint(my_provider, my_first_tracepoint, i, argv[i]);
  52     }
  53
  54     return 0;
  55 }
  56 ~~~
  57
  58 `TRACEPOINT_DEFINE` must be defined into exactly one translation unit (C
  59 source file) of the user application, before including the tracepoint provider
  60 header file. `TRACEPOINT_DEFINE` is discussed further in
  61 [Building/linking tracepoint providers and the user application](#doc-building-tracepoint-providers-and-user-application).
  62
  63 As another example, remember this definition we wrote in a previous
  64 section (comments are stripped):
  65
  66 ~~~ c
  67 /* for struct stat */
  68 #include <sys/types.h>
  69 #include <sys/stat.h>
  70 #include <unistd.h>
  71
  72 TRACEPOINT_EVENT(
  73     my_provider,
  74     my_tracepoint,
  75     TP_ARGS(
  76         int, my_int_arg,
  77         char*, my_str_arg,
  78         struct stat*, st
  79     ),
  80     TP_FIELDS(
  81         ctf_integer(int, my_constant_field, 23 + 17)
  82         ctf_integer(int, my_int_arg_field, my_int_arg)
  83         ctf_integer(int, my_int_arg_field2, my_int_arg * my_int_arg)
  84         ctf_integer(int, sum4_field, my_str_arg[0] + my_str_arg[1] +
  85                                      my_str_arg[2] + my_str_arg[3])
  86         ctf_string(my_str_arg_field, my_str_arg)
  87         ctf_integer_hex(off_t, size_field, st->st_size)
  88         ctf_float(double, size_dbl_field, (double) st->st_size)
  89         ctf_sequence_text(char, half_my_str_arg_field, my_str_arg,
  90                           size_t, strlen(my_str_arg) / 2)
  91     )
  92 )
  93 ~~~
  94
  95 Here's an example of calling it:
  96
  97 ~~~ c
  98 #define TRACEPOINT_DEFINE
  99 #include "tp.h"
 100
 101 int main(void)
 102 {
 103     struct stat s;
 104
 105     stat("/etc/fstab", &s);
 106
 107     tracepoint(my_provider, my_tracepoint, 23, "Hello, World!", &s);
 108
 109     return 0;
 110 }
 111 ~~~
 112
 113 When viewing the trace, assuming the file size of `/etc/fstab` is
 114 301&nbsp;bytes, the event generated by the execution of this tracepoint
 115 should have the following fields, in this order:
 116
 117 ~~~ text
 118 my_constant_field           40
 119 my_int_arg_field            23
 120 my_int_arg_field2           529
 121 sum4_field                  389
 122 my_str_arg_field            "Hello, World!"
 123 size_field                  0x12d
 124 size_dbl_field              301.0
 125 half_my_str_arg_field       "Hello,"
 126 ~~~