Commit | Line | Data |
---|---|---|
4ddbd0b7 PP |
1 | tracelog(3) |
2 | =========== | |
3 | :object-type: macro | |
4 | ||
5 | ||
6 | NAME | |
7 | ---- | |
1d41a8d7 | 8 | tracelog, vtracelog - LTTng-UST printf(3)-like interface with a log level |
4ddbd0b7 PP |
9 | |
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
13 | [verse] | |
14 | *#include <lttng/tracelog.h>* | |
15 | ||
16 | [verse] | |
17 | #define *tracelog*('level', 'fmt', ...) | |
d6208c2d | 18 | #define *vtracelog*('level', 'fmt', 'ap') |
4ddbd0b7 PP |
19 | |
20 | Link with `-llttng-ust`. | |
21 | ||
22 | ||
23 | DESCRIPTION | |
24 | ----------- | |
d6208c2d PP |
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. | |
4ddbd0b7 | 29 | |
d6208c2d PP |
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. | |
4ddbd0b7 PP |
42 | |
43 | The available values for the 'level' parameter are: | |
44 | ||
45 | include::log-levels.txt[] | |
46 | ||
d6208c2d PP |
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. | |
4ddbd0b7 | 50 | |
d6208c2d PP |
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. | |
4ddbd0b7 | 56 | |
d6208c2d | 57 | The `tracelog()` and `vtracelog()` events contain the following fields: |
4ddbd0b7 PP |
58 | |
59 | [options="header"] | |
8902dadc PP |
60 | |=== |
61 | |Field name |Description | |
62 | ||
63 | |`line` | |
d01f365a | 64 | |Line in source file where `tracelog()` was called. |
8902dadc PP |
65 | |
66 | |`file` | |
d01f365a | 67 | |Source file from which `tracelog()` was called. |
8902dadc PP |
68 | |
69 | |`func` | |
d01f365a | 70 | |Function name from which `tracelog()` was called. |
8902dadc PP |
71 | |
72 | |`msg` | |
d01f365a | 73 | |Formatted string output. |
8902dadc | 74 | |=== |
4ddbd0b7 | 75 | |
d6208c2d PP |
76 | If you do not need to attach a specific log level to a |
77 | `tracelog()`/`vtracelog()` call, use man:tracef(3) instead. | |
4ddbd0b7 PP |
78 | |
79 | See also the <<limitations,LIMITATIONS>> section below for important | |
bd9bb3c7 | 80 | limitations to consider when using `tracelog()` or `vtracelog()`. |
4ddbd0b7 PP |
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"] | |
636cf2a0 PP |
117 | ---- |
118 | $ cc -o app app.c -llttng-ust | |
119 | ---- | |
4ddbd0b7 PP |
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"] | |
636cf2a0 PP |
125 | ---- |
126 | $ lttng create my-session | |
127 | $ lttng enable-event --userspace 'lttng_ust_tracelog:*' | |
128 | $ lttng start | |
129 | ---- | |
4ddbd0b7 PP |
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"] | |
636cf2a0 PP |
135 | ---- |
136 | $ lttng enable-event --userspace 'lttng_ust_tracelog:*' \ | |
4ddbd0b7 | 137 | --loglevel=TRACE_INFO |
636cf2a0 | 138 | ---- |
4ddbd0b7 PP |
139 | |
140 | Next, start the program to be traced: | |
141 | ||
142 | [role="term"] | |
636cf2a0 PP |
143 | ---- |
144 | $ ./app a few arguments passed to this application | |
145 | ---- | |
4ddbd0b7 PP |
146 | |
147 | Finally, stop the tracing session, and inspect the recorded events: | |
148 | ||
149 | [role="term"] | |
636cf2a0 PP |
150 | ---- |
151 | $ lttng stop | |
152 | $ lttng view | |
153 | ---- | |
4ddbd0b7 PP |
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), | |
d6208c2d | 174 | man:vtracef(3), |
4ddbd0b7 PP |
175 | man:lttng-ust(3), |
176 | man:lttng(1), | |
177 | man:printf(3) |