doc/man/lttng_ust_tracef.3.txt

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