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