doc/man/lttng_ust_tracef.3.txt

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