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"] | |
50 | |=============================================================== | |
51 | | Field name | Description | |
52 | | `line` | Line in source file where `tracelog()` was called | |
53 | | `file` | Source file from which `tracelog()` was called | |
54 | | `func` | Function name from which `tracelog()` was called | |
55 | | `msg` | Formatted string output | |
56 | |=============================================================== | |
57 | ||
58 | If you do not need to attach a specific log level to a `tracelog()` | |
59 | call, use man:tracef(3) instead. | |
60 | ||
61 | See also the <<limitations,LIMITATIONS>> section below for important | |
62 | limitations to consider when using `tracelog()`. | |
63 | ||
64 | ||
65 | [[example]] | |
66 | EXAMPLE | |
67 | ------- | |
68 | Here's a usage example of `tracelog()`: | |
69 | ||
70 | ------------------------------------------------------------------- | |
71 | #include <stdlib.h> | |
72 | #include <lttng/tracelog.h> | |
73 | ||
74 | int main(int argc, char *argv[]) | |
75 | { | |
76 | int i; | |
77 | ||
78 | if (argc < 2) { | |
79 | tracelog(TRACE_CRIT, "Not enough arguments: %d", argc); | |
80 | return EXIT_FAILURE; | |
81 | } | |
82 | ||
83 | tracelog(TRACE_INFO, "Starting app with %d arguments", argc); | |
84 | ||
85 | for (i = 0; i < argc; i++) { | |
86 | tracelog(TRACE_DEBUG, "Argument %d: %s", i, argv[i]); | |
87 | } | |
88 | ||
89 | tracelog(TRACE_INFO, "Exiting app"); | |
90 | ||
91 | return EXIT_SUCCESS; | |
92 | } | |
93 | ------------------------------------------------------------------- | |
94 | ||
95 | This C source file, saved as `app.c`, can be compiled into a program | |
96 | like this: | |
97 | ||
98 | [role="term"] | |
99 | --------------------------- | |
100 | cc -o app app.c -llttng-ust | |
101 | --------------------------- | |
102 | ||
103 | You can create an LTTng tracing session, enable all the `tracelog()` | |
104 | events, and start the created tracing session like this: | |
105 | ||
106 | [role="term"] | |
107 | --------------------------------------------------- | |
108 | lttng create my-session | |
109 | lttng enable-event --userspace 'lttng_ust_tracelog:*' | |
110 | lttng start | |
111 | --------------------------------------------------- | |
112 | ||
113 | Or you can enable `tracelog()` events matching a log level at least | |
114 | as severe as a given log level: | |
115 | ||
116 | [role="term"] | |
117 | ------------------------------------------------------- | |
118 | lttng enable-event --userspace 'lttng_ust_tracelog:*' \ | |
119 | --loglevel=TRACE_INFO | |
120 | ------------------------------------------------------- | |
121 | ||
122 | Next, start the program to be traced: | |
123 | ||
124 | [role="term"] | |
125 | ------------------------------------------------ | |
126 | ./app a few arguments passed to this application | |
127 | ------------------------------------------------ | |
128 | ||
129 | Finally, stop the tracing session, and inspect the recorded events: | |
130 | ||
131 | [role="term"] | |
132 | ---------- | |
133 | lttng stop | |
134 | lttng view | |
135 | ---------- | |
136 | ||
137 | ||
138 | [[limitations]] | |
139 | LIMITATIONS | |
140 | ----------- | |
141 | :macro-name: tracelog | |
142 | ||
143 | include::tracef-tracelog-limitations.txt[] | |
144 | ||
145 | ||
146 | include::common-footer.txt[] | |
147 | ||
148 | include::common-copyrights.txt[] | |
149 | ||
150 | include::common-authors.txt[] | |
151 | ||
152 | ||
153 | SEE ALSO | |
154 | -------- | |
155 | man:tracef(3), | |
156 | man:lttng-ust(3), | |
157 | man:lttng(1), | |
158 | man:printf(3) |