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