doc/man/tracef.3.txt

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