doc/man/tracelog.3.txt

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