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