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