doc/man/lttng_ust_tracelog.3.txt

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