doc/man/lttng_ust_tracelog.3.txt

   1 lttng_ust_tracelog(3)
   2 =====================
   3 :object-type: macro
   4
   5
   6 NAME
   7 ----
   8 lttng_ust_tracelog, lttng_ust_vtracelog - LTTng-UST printf(3)-like interface with a log level
   9
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 *#include <lttng/tracelog.h>*
  15
  16 [verse]
  17 #define *lttng_ust_tracelog*('level', 'fmt', ...)
  18 #define *lttng_ust_vtracelog*('level', 'fmt', 'ap')
  19
  20 Link with `-llttng-ust -llttng-ust-common`.
  21
  22
  23 DESCRIPTION
  24 -----------
  25 The LTTng-UST `lttng_ust_tracelog()` and `lttng_ust_vtracelog()` API
  26 allows you to trace your application with the help of simple
  27 man:printf(3)-like and man:vprintf(3)-like macros, with an additional
  28 parameter for the desired log level.
  29
  30 The 'fmt' argument is passed directly as the 'fmt' parameter of
  31 man:vasprintf(3), as well as:
  32
  33 For `lttng_ust_tracelog()`::
  34     The optional parameters following 'fmt'.
  35
  36 For `lttng_ust_vtracelog()`::
  37     The 'ap' parameter as the 'ap' parameter of man:vasprintf(3)
  38     (`va_list` type).
  39
  40 The purpose of `lttng_ust_tracelog()` and `lttng_ust_vtracelog()` is to
  41 ease the migration from logging to tracing.
  42
  43 The available values for the 'level' parameter are:
  44
  45 include::log-levels.txt[]
  46
  47 To use `lttng_ust_tracelog()` or `lttng_ust_vtracelog()`, include
  48 `<lttng/tracelog.h>` where you need it, and link your application with
  49 `liblttng-ust` and `liblttng-ust-common`. See the <<example,EXAMPLE>>
  50 section below for a complete usage example.
  51
  52 Once your application is instrumented with `lttng_ust_tracelog()` and/or
  53 `lttng_ust_vtracelog()` calls and ready to run, use
  54 man:lttng-enable-event(1) to enable the `lttng_ust_tracelog:*` event.
  55 You can isolate specific log levels with the nloption:--loglevel and
  56 nloption:--loglevel-only options of this command.
  57
  58 The `lttng_ust_tracelog()` and `lttng_ust_vtracelog()` events contain
  59 the following fields:
  60
  61 [options="header"]
  62 |===
  63 |Field name |Description
  64
  65 |`line`
  66 |Line in source file where `lttng_ust_tracelog()` was called.
  67
  68 |`file`
  69 |Source file from which `lttng_ust_tracelog()` was called.
  70
  71 |`func`
  72 |Function name from which `lttng_ust_tracelog()` was called.
  73
  74 |`msg`
  75 |Formatted string output.
  76 |===
  77
  78 If you do not need to attach a specific log level to a
  79 `lttng_ust_tracelog()`/`lttng_ust_vtracelog()` call, use
  80 man:lttng_ust_tracef(3) instead.
  81
  82 See also the <<limitations,LIMITATIONS>> section below for important
  83 limitations to consider when using `lttng_ust_tracelog()` or
  84 `lttng_ust_vtracelog()`.
  85
  86
  87 [[example]]
  88 EXAMPLE
  89 -------
  90 Here's a usage example of `lttng_ust_tracelog()`:
  91
  92 -------------------------------------------------------------------
  93 #include <stdlib.h>
  94 #include <lttng/tracelog.h>
  95
  96 int main(int argc, char *argv[])
  97 {
  98     int i;
  99
 100     if (argc < 2) {
 101         lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_CRIT,
 102                            "Not enough arguments: %d", argc);
 103         return EXIT_FAILURE;
 104     }
 105
 106     lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO,
 107                        "Starting app with %d arguments", argc);
 108
 109     for (i = 0; i < argc; i++) {
 110         lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG,
 111                            "Argument %d: %s", i, argv[i]);
 112     }
 113
 114     lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO,
 115                        "Exiting app");
 116     return EXIT_SUCCESS;
 117 }
 118 -------------------------------------------------------------------
 119
 120 This C source file, saved as `app.c`, can be compiled into a program
 121 like this:
 122
 123 [role="term"]
 124 ----
 125 $ cc -o app app.c -llttng-ust -llttng-ust-common
 126 ----
 127
 128 You can create an LTTng tracing session, enable all the
 129 `lttng_ust_tracelog()` events, and start the created tracing session
 130 like this:
 131
 132 [role="term"]
 133 ----
 134 $ lttng create my-session
 135 $ lttng enable-event --userspace 'lttng_ust_tracelog:*'
 136 $ lttng start
 137 ----
 138
 139 Or you can enable `lttng_ust_tracelog()` events matching a log level at
 140 least as severe as a given log level:
 141
 142 [role="term"]
 143 ----
 144 $ lttng enable-event --userspace 'lttng_ust_tracelog:*' \
 145                      --loglevel=INFO
 146 ----
 147
 148 Next, start the program to be traced:
 149
 150 [role="term"]
 151 ----
 152 $ ./app a few arguments passed to this application
 153 ----
 154
 155 Finally, stop the tracing session, and inspect the recorded events:
 156
 157 [role="term"]
 158 ----
 159 $ lttng stop
 160 $ lttng view
 161 ----
 162
 163
 164 [[limitations]]
 165 LIMITATIONS
 166 -----------
 167 :macro-suffix: tracelog
 168
 169 include::tracef-tracelog-limitations.txt[]
 170
 171
 172 include::common-footer.txt[]
 173
 174 include::common-copyrights.txt[]
 175
 176 include::common-authors.txt[]
 177
 178
 179 SEE ALSO
 180 --------
 181 man:lttng_ust_tracef(3),
 182 man:lttng_ust_vtracef(3),
 183 man:lttng-ust(3),
 184 man:lttng(1),
 185 man:printf(3)