contents/using-lttng/instrumenting/c-application/tracef.md

   1 ---
   2 id: tracef
   3 since: 2.5
   4 ---
   5
   6 `tracef()` is a small LTTng-UST API to avoid defining your own
   7 tracepoints and tracepoint providers. The signature of `tracef()` is
   8 the same as `printf()`'s.
   9
  10 The `tracef()` utility function was developed to make user space tracing
  11 super simple, albeit with notable disadvantages compared to custom,
  12 full-fledged tracepoint providers:
  13
  14   * All generated events have the same provider/event names, respectively
  15     `lttng-ust-tracef` and `event`.
  16   * There's no static type checking.
  17   * The only event field you actually get, named `msg`, is a string
  18     potentially containing the values you passed to the function
  19     using your own format. This also means that you cannot use filtering
  20     using a custom expression at runtime because there are no isolated
  21     fields.
  22   * Since `tracef()` uses C standard library's `vasprintf()` function
  23     in the background to format the strings at runtime, its
  24     expected performance is lower than using custom tracepoint providers
  25     with typed fields, which do not require a conversion to a string.
  26
  27 Thus, `tracef()` is useful for quick prototyping and debugging, but
  28 should not be considered for any permanent/serious application
  29 instrumentation.
  30
  31 To use `tracef()`, first include `<lttng/tracef.h>` in the C source file
  32 where you need to insert probes:
  33
  34 ~~~ c
  35 #include <lttng/tracef.h>
  36 ~~~
  37
  38 Use `tracef()` like you would use `printf()` in your source code, for
  39 example:
  40
  41 ~~~ c
  42     /* ... */
  43
  44     tracef("my message, my integer: %d", my_integer);
  45
  46     /* ... */
  47 ~~~
  48
  49 Link your application with `liblttng-ust`:
  50
  51 <pre class="term">
  52 gcc -o app app.c <strong>-llttng-ust</strong>
  53 </pre>
  54
  55 Execute the application as usual:
  56
  57 <pre class="term">
  58 ./app
  59 </pre>
  60
  61 Voilà! Use the `lttng` command line tool to
  62 [control tracing](#doc-controlling-tracing).