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