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