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 | `line`     | Line in source file where `tracelog()` was called
  53 | `file`     | Source file from which `tracelog()` was called
  54 | `func`     | Function name from which `tracelog()` was called
  55 | `msg`      | Formatted string output
  56 |===============================================================
  57
  58 If you do not need to attach a specific log level to a `tracelog()`
  59 call, use man:tracef(3) instead.
  60
  61 See also the <<limitations,LIMITATIONS>> section below for important
  62 limitations to consider when using `tracelog()`.
  63
  64
  65 [[example]]
  66 EXAMPLE
  67 -------
  68 Here's a usage example of `tracelog()`:
  69
  70 -------------------------------------------------------------------
  71 #include <stdlib.h>
  72 #include <lttng/tracelog.h>
  73
  74 int main(int argc, char *argv[])
  75 {
  76     int i;
  77
  78     if (argc < 2) {
  79         tracelog(TRACE_CRIT, "Not enough arguments: %d", argc);
  80         return EXIT_FAILURE;
  81     }
  82
  83     tracelog(TRACE_INFO, "Starting app with %d arguments", argc);
  84
  85     for (i = 0; i < argc; i++) {
  86         tracelog(TRACE_DEBUG, "Argument %d: %s", i, argv[i]);
  87     }
  88
  89     tracelog(TRACE_INFO, "Exiting app");
  90
  91     return EXIT_SUCCESS;
  92 }
  93 -------------------------------------------------------------------
  94
  95 This C source file, saved as `app.c`, can be compiled into a program
  96 like this:
  97
  98 [role="term"]
  99 ---------------------------
 100 cc -o app app.c -llttng-ust
 101 ---------------------------
 102
 103 You can create an LTTng tracing session, enable all the `tracelog()`
 104 events, and start the created tracing session like this:
 105
 106 [role="term"]
 107 ---------------------------------------------------
 108 lttng create my-session
 109 lttng enable-event --userspace 'lttng_ust_tracelog:*'
 110 lttng start
 111 ---------------------------------------------------
 112
 113 Or you can enable `tracelog()` events matching a log level at least
 114 as severe as a given log level:
 115
 116 [role="term"]
 117 -------------------------------------------------------
 118 lttng enable-event --userspace 'lttng_ust_tracelog:*' \
 119                    --loglevel=TRACE_INFO
 120 -------------------------------------------------------
 121
 122 Next, start the program to be traced:
 123
 124 [role="term"]
 125 ------------------------------------------------
 126 ./app a few arguments passed to this application
 127 ------------------------------------------------
 128
 129 Finally, stop the tracing session, and inspect the recorded events:
 130
 131 [role="term"]
 132 ----------
 133 lttng stop
 134 lttng view
 135 ----------
 136
 137
 138 [[limitations]]
 139 LIMITATIONS
 140 -----------
 141 :macro-name: tracelog
 142
 143 include::tracef-tracelog-limitations.txt[]
 144
 145
 146 include::common-footer.txt[]
 147
 148 include::common-copyrights.txt[]
 149
 150 include::common-authors.txt[]
 151
 152
 153 SEE ALSO
 154 --------
 155 man:tracef(3),
 156 man:lttng-ust(3),
 157 man:lttng(1),
 158 man:printf(3)