doc/man: reorganize source for tables
[lttng-ust.git] / 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)
This page took 0.037811 seconds and 6 git commands to generate.