doc/man/tracef.3.txt

   1 tracef(3)
   2 =========
   3 :object-type: macro
   4
   5
   6 NAME
   7 ----
   8 tracef, vtracef - LTTng-UST printf(3)-like interface
   9
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 *#include <lttng/tracef.h>*
  15
  16 [verse]
  17 #define *tracef*('fmt', ...)
  18 #define *vtracef*('fmt', 'va_list' ap)
  19
  20 Link with `-llttng-ust`.
  21
  22
  23 DESCRIPTION
  24 -----------
  25 The LTTng-UST `tracef()` API allows you to trace your application with
  26 the help of a simple man:printf(3)-like macro. The 'fmt' argument is
  27 passed directly to the 'fmt' parameter of man:vasprintf(3), as well as
  28 the optional parameters following 'fmt'.
  29
  30 To use `tracef()` or `vtracef()`, include `<lttng/tracef.h>` where you need it,
  31 and link your application with `liblttng-ust`. See the <<example,EXAMPLE>>
  32 section below for a complete usage example.
  33
  34 Once your application is instrumented with `tracef()` or `vtracef()` calls and
  35 ready to run, use man:lttng-enable-event(1) to enable the
  36 `lttng_ust_tracef:*` event.
  37
  38 The `tracef()` events contain a single field, named `msg`, which is the
  39 formatted string output.
  40
  41 If you need to attach a specific log level to a `tracef()` call, use
  42 man:tracelog(3) instead.
  43
  44 See also the <<limitations,LIMITATIONS>> section below for important
  45 limitations to consider when using `tracef()` or `vtracef()`.
  46
  47
  48 [[example]]
  49 EXAMPLE
  50 -------
  51 Here's a usage example of `tracef()`:
  52
  53 -------------------------------------------------------------------
  54 #include <stdlib.h>
  55 #include <lttng/tracef.h>
  56
  57 int main(void)
  58 {
  59     int i;
  60
  61     for (i = 0; i < 25; i++) {
  62         tracef("my message: %s, this integer: %d", "a message", i);
  63     }
  64
  65     return EXIT_SUCCESS;
  66 }
  67 -------------------------------------------------------------------
  68
  69 This C source file, saved as `app.c`, can be compiled into a program
  70 like this:
  71
  72 [role="term"]
  73 ----
  74 $ cc -o app app.c -llttng-ust
  75 ----
  76
  77 You can create an LTTng tracing session, enable the `tracef()` events,
  78 and start the created tracing session like this:
  79
  80 [role="term"]
  81 ----
  82 $ lttng create my-session
  83 $ lttng enable-event --userspace 'lttng_ust_tracef:*'
  84 $ lttng start
  85 ----
  86
  87 Next, start the program to be traced:
  88
  89 [role="term"]
  90 ----
  91 $ ./app
  92 ----
  93
  94 Finally, stop the tracing session, and inspect the recorded events:
  95
  96 [role="term"]
  97 ----
  98 $ lttng stop
  99 $ lttng view
 100 ----
 101
 102
 103 [[limitations]]
 104 LIMITATIONS
 105 -----------
 106 :macro-name: tracef
 107
 108 include::tracef-tracelog-limitations.txt[]
 109
 110
 111 include::common-footer.txt[]
 112
 113 include::common-copyrights.txt[]
 114
 115 include::common-authors.txt[]
 116
 117
 118 SEE ALSO
 119 --------
 120 man:tracelog(3),
 121 man:lttng-ust(3),
 122 man:lttng(1),
 123 man:printf(3)