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