doc/man/tracelog.3.txt

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