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