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

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