Commit | Line | Data |
---|---|---|
048f01ef PP |
1 | /*! |
2 | @mainpage Bonjour! | |
3 | ||
4 | Welcome to the <strong>\lt_api</strong> (liblttng-ctl) documentation! | |
5 | ||
6 | The | |
7 | <a href="https://lttng.org/"><em>Linux Trace Toolkit: next generation</em></a> | |
8 | is an open-source software package used for correlated tracing of the | |
9 | Linux kernel, user applications, and user libraries. | |
10 | ||
11 | liblttng-ctl, which is part of the LTTng-tools project, makes it | |
12 | possible to control <a href="https://lttng.org/">LTTng</a> tracing, but | |
13 | also to | |
14 | \ref api_trigger "receive notifications when specific events occur". | |
15 | ||
16 | <h2>Plumbing</h2> | |
17 | ||
18 | The following diagram shows the components of LTTng: | |
19 | ||
20 | @image html plumbing.png "Components of LTTng." | |
21 | ||
22 | As you can see, liblttng-ctl is a bridge between a user application | |
23 | and a session daemon (see \lt_man{lttng-sessiond,8} and | |
24 | \ref api-gen-sessiond-conn "Session daemon connection"). | |
25 | ||
26 | The \lt_man{lttng,1} command-line tool which ships with LTTng-tools, for | |
27 | example, uses liblttng-ctl to perform its commands. | |
28 | ||
29 | See the | |
30 | <a href="https://lttng.org/docs/v\lt_version_maj_min/#doc-plumbing"><em>Components of LTTng</em></a> | |
31 | section of the LTTng Documentation to learn more. | |
32 | ||
33 | <h2>Contents</h2> | |
34 | ||
35 | This API documentation has three main modules: | |
36 | ||
37 | - The \ref api_session makes it possible to create, manipulate | |
38 | (\ref api_session_snapshot "take a snapshot", | |
39 | \ref api_session_rotation "rotate", | |
40 | \ref api_session_clear "clear", and the rest), and destroy | |
41 | <em>recording sessions</em>. | |
42 | ||
43 | A recording session is a per-Unix user dialogue for everything related | |
44 | to event recording. | |
45 | ||
46 | A recording session owns \lt_obj_channels which | |
47 | own \lt_obj_rers. Those objects constitute | |
48 | the main configuration of a recording session. | |
49 | ||
50 | - The \ref api_inst_pt makes it possible to get details about the | |
51 | available LTTng tracepoints, Java/Python loggers, and Linux kernel | |
52 | system calls without needing any \lt_obj_session. | |
53 | ||
54 | - The \ref api_trigger makes it possible to create and register | |
55 | <em>triggers</em>. | |
56 | ||
57 | A trigger associates a condition to one or more actions: when the | |
58 | condition of a trigger is satisfied, LTTng attempts to execute its | |
59 | actions. | |
60 | ||
61 | This API is fully decoupled from the \ref api_session. | |
62 | ||
63 | Amongst the interesting available trigger conditions and actions | |
64 | are the | |
65 | \link #LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES <em>event rule matches</em>\endlink | |
66 | condition and the | |
67 | \link #LTTNG_ACTION_TYPE_NOTIFY <em>notify</em>\endlink | |
68 | action. With those, your application can receive an asynchronous | |
69 | message (a notification) when a specified event rule matches | |
70 | an LTTng event. | |
71 | ||
72 | The three modules above often refer to the \ref api_gen which offers | |
73 | common enumerations, macros, and functions. | |
74 | ||
75 | See <a href="modules.html">API reference</a> for the complete table | |
76 | of contents. | |
77 | ||
78 | <h2>Build with liblttng-ctl</h2> | |
79 | ||
80 | To build an application with liblttng-ctl: | |
81 | ||
82 | <dl> | |
83 | <dt>Header file | |
84 | <dd> | |
85 | Include <code>%lttng/lttng.h</code>: | |
86 | ||
87 | @code | |
88 | #include <lttng/lttng.h> | |
89 | @endcode | |
90 | ||
91 | With | |
92 | <a href="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</a>, | |
93 | get the required C flags with: | |
94 | ||
95 | @code{.unparsed} | |
96 | $ pkg-config --cflags lttng-ctl | |
97 | @endcode | |
98 | ||
99 | <dt>Linking | |
100 | <dd> | |
101 | Link your application with <code>liblttng-ctl</code>: | |
102 | ||
103 | @code{.unparsed} | |
104 | $ cc my-app.o ... -llttng-ctl | |
105 | @endcode | |
106 | ||
107 | With pkg-config, get the required linker options with: | |
108 | ||
109 | @code{.unparsed} | |
110 | $ pkg-config --libs lttng-ctl | |
111 | @endcode | |
112 | </dl> | |
113 | ||
114 | @defgroup api_gen General API | |
115 | ||
116 | The general \lt_api offers: | |
117 | ||
118 | - \ref lttng_error_code "Error code enumerators" and lttng_strerror(). | |
119 | ||
120 | - \ref api-gen-sessiond-conn "Session daemon connection" functions: | |
121 | ||
122 | - lttng_session_daemon_alive() | |
123 | - lttng_set_tracing_group() | |
124 | ||
125 | <h1>\anchor api-gen-sessiond-conn Session daemon connection</h1> | |
126 | ||
127 | Many functions of the \lt_api require a connection to a listening LTTng | |
128 | session daemon (see \lt_man{lttng-sessiond,8}) to control LTTng tracing. | |
129 | ||
130 | liblttng-ctl connects to a session daemon through a Unix domain socket | |
131 | when you call some of its public functions, \em not when it loads. | |
132 | ||
133 | Each Unix user may have its own independent running session daemon. | |
134 | However, liblttng-ctl must connect to the session daemon of the | |
135 | \c root user (the root session daemon) to control Linux kernel tracing. | |
136 | ||
137 | How liblttng-ctl chooses which session daemon to connect to is as | |
138 | follows, considering \lt_var{U} is the Unix user of the process running | |
139 | liblttng-ctl: | |
140 | ||
141 | <dl> | |
142 | <dt>\lt_var{U} is \c root | |
143 | <dd>Connect to the root session daemon. | |
144 | ||
145 | <dt>\lt_var{U} is not \c root | |
146 | <dd> | |
147 | <dl> | |
148 | <dt>If \lt_var{U} is part of the current liblttng-ctl Unix <em>tracing group</em> | |
149 | <dd> | |
150 | Try to connect to the root session daemon. | |
151 | ||
152 | If the root session daemon isn't running, connect to the | |
153 | session daemon of \lt_var{U}. | |
154 | ||
155 | <dt>If \lt_var{U} is not part of the tracing group | |
156 | <dd> | |
157 | Connect to the session daemon of \lt_var{U}. | |
158 | </dl> | |
159 | </dl> | |
160 | ||
161 | The Unix tracing group of the root session daemon is one of: | |
162 | ||
163 | <dl> | |
164 | <dt> | |
165 | With the <code>\--group=<em>GROUP</em></code> option of the root | |
166 | session daemon | |
167 | <dd> | |
168 | Exactly <code><em>GROUP</em></code>. | |
169 | ||
170 | In that case, you must call lttng_set_tracing_group(), passing | |
171 | exactly <code><em>GROUP</em></code>, \em before you call a | |
172 | liblttng-ctl function which needs to connect to a session daemon. | |
173 | ||
174 | <dt> | |
175 | Without the <code>\--group</code> option of the root | |
176 | session daemon | |
177 | <dd> | |
178 | Exactly \c tracing (also the default Unix tracing group of | |
179 | liblttng-ctl, therefore you don't need to call | |
180 | lttng_set_tracing_group()). | |
181 | </dl> | |
182 | ||
183 | Check that your application can successfully connect to a session daemon | |
184 | with lttng_session_daemon_alive(). | |
185 | ||
186 | LTTng-instrumented user applications automatically register to both the | |
187 | root and user session daemons. This makes it possible for both session | |
188 | daemons to list the available instrumented applications and their | |
189 | \ref api_inst_pt "instrumentation points". | |
190 | ||
191 | @defgroup api_session Recording session API | |
192 | ||
193 | A <strong><em>recording session</em></strong> is a stateful dialogue | |
194 | between an application and a session daemon for everything related to | |
195 | event recording. | |
196 | ||
197 | Everything that you do when you control LTTng tracers to record events | |
198 | happens within a recording session. In particular, a recording session: | |
199 | ||
200 | - Has its own name, unique for a given session daemon. | |
201 | ||
202 | - Has its own set of trace files, if any. | |
203 | ||
204 | - Has its own state of | |
205 | \link lttng_session::enabled activity\endlink (started or stopped). | |
206 | ||
207 | An active recording session is an implicit | |
208 | \lt_obj_rer condition. | |
209 | ||
210 | - Has its own \ref api-session-modes "mode" | |
211 | (local, network streaming, snapshot, or live). | |
212 | ||
213 | - Has its own \lt_obj_channels to which are attached | |
214 | their own recording event rules. | |
215 | ||
216 | - Has its own \ref api_pais "process attribute inclusion sets". | |
217 | ||
218 | Those attributes and objects are completely isolated between different | |
219 | recording sessions. | |
220 | ||
221 | A recording session is like an | |
222 | <a href="https://en.wikipedia.org/wiki/Automated_teller_machine">ATM</a> | |
223 | session: the operations you do on the | |
224 | banking system through the ATM don't alter the data of other users of | |
225 | the same system. In the case of the ATM, a session lasts as long as your | |
226 | bank card is inside. In the case of LTTng, a recording session lasts | |
227 | from a call to lttng_create_session_ext() to the completion of its | |
228 | destruction operation (which you can initiate with | |
229 | lttng_destroy_session_ext()). | |
230 | ||
231 | A recording session belongs to a session daemon (see | |
232 | \lt_man{lttng-sessiond,8} and | |
233 | \ref api-gen-sessiond-conn "Session daemon connection"). For a given | |
234 | session daemon, each Unix user has its own, private recording sessions. | |
235 | Note, however, that the \c root Unix user may operate on or destroy | |
236 | another user's recording session. | |
237 | ||
238 | @image html many-sessions.png "Each Unix user has its own, private recording sessions." | |
239 | ||
240 | @sa The <em>RECORDING SESSION</em> section of \lt_man{lttng-concepts,7}. | |
241 | ||
242 | <h1>Operations</h1> | |
243 | ||
244 | The recording session operations are: | |
245 | ||
246 | <table> | |
247 | <tr> | |
248 | <th>Operation | |
249 | <th>Means | |
250 | <tr> | |
251 | <td>Creation | |
252 | <td> | |
253 | -# Create a \lt_obj_session_descr | |
254 | with one of the dedicated creation functions depending on the | |
255 | \ref api-session-modes "recording session mode". | |
256 | ||
257 | -# Call lttng_create_session_ext(), passing the recording session | |
258 | descriptor of step 1. | |
259 | ||
260 | -# When you're done with the recording session descriptor, destroy | |
261 | it with lttng_session_descriptor_destroy(). | |
262 | ||
263 | @sa \lt_man{lttng-create,1} | |
264 | <tr> | |
265 | <td>Destruction | |
266 | <td> | |
267 | -# Call lttng_destroy_session_ext(), passing the name of the | |
268 | recording session to destroy. | |
269 | ||
270 | This function initiates a destruction operation, returning | |
271 | immediately. | |
272 | ||
273 | This function can set a pointer to a | |
274 | \ref api_session_destr_handle "destruction handle" | |
275 | (#lttng_destruction_handle) so that you can wait for the | |
276 | completion of the operation. Without such a handle, you can't | |
277 | know when the destruction operation completes and whether or | |
278 | not it does successfully. | |
279 | ||
280 | -# <strong>If you have a destruction handle from | |
281 | step 1</strong>: | |
282 | ||
283 | -# Call lttng_destruction_handle_wait_for_completion() to wait | |
284 | for the completion of the destruction operation. | |
285 | ||
286 | -# Call lttng_destruction_handle_get_result() to get whether or | |
287 | not the destruction operation successfully completed. | |
288 | ||
289 | You can also call | |
290 | lttng_destruction_handle_get_rotation_state() and | |
291 | lttng_destruction_handle_get_archive_location() at this | |
292 | point. | |
293 | ||
294 | -# Destroy the destruction handle with | |
295 | lttng_destruction_handle_destroy(). | |
296 | ||
297 | @sa \lt_man{lttng-destroy,1} | |
298 | <tr> | |
299 | <td>Basic property access | |
300 | <td> | |
301 | See: | |
302 | ||
303 | - The members of #lttng_session | |
304 | - lttng_session_descriptor_get_session_name() | |
305 | - lttng_session_get_creation_time() | |
306 | - lttng_set_session_shm_path() | |
307 | - lttng_data_pending() | |
308 | <tr> | |
309 | <td>\lt_obj_c_domain access | |
310 | <td> | |
311 | -# Call lttng_list_domains(), passing the name of the recording | |
312 | session of which to get the tracing domains. | |
313 | ||
314 | This function sets a pointer to an array of | |
315 | \link #lttng_domain tracing domain summaries\endlink | |
316 | and returns the number of entries. | |
317 | ||
318 | -# Access the properties of each tracing domain summary through | |
319 | structure members. | |
320 | ||
321 | -# When you're done with the array of tracing domain summaries, | |
322 | free it with <code>free()</code>. | |
323 | <tr> | |
324 | <td>\lt_obj_c_channel access | |
325 | <td> | |
326 | -# Create a \link #lttng_handle recording session handle\endlink | |
327 | with lttng_create_handle() to specify the name of the | |
328 | recording session and the summary of the | |
329 | \lt_obj_domain of the channels to access. | |
330 | ||
331 | -# Call lttng_list_channels(), passing the recording session | |
332 | handle of step 1. | |
333 | ||
334 | This function sets a pointer to an array of | |
335 | \link #lttng_channel channel summaries\endlink | |
336 | and returns the number of entries. | |
337 | ||
338 | -# Destroy the recording session handle of step 1 with | |
339 | lttng_destroy_handle(). | |
340 | ||
341 | -# Access the \ref api-channel-channel-props "properties" of each | |
342 | channel summary through structure members or using dedicated | |
343 | getters. | |
344 | ||
345 | -# When you're done with the array of channel summaries, | |
346 | free it with <code>free()</code>. | |
347 | <tr> | |
348 | <td>Activity control | |
349 | <td> | |
350 | See: | |
351 | ||
352 | - lttng_start_tracing() | |
353 | - lttng_stop_tracing() | |
354 | - lttng_stop_tracing_no_wait() | |
355 | ||
356 | The #LTTNG_ACTION_TYPE_START_SESSION and | |
357 | #LTTNG_ACTION_TYPE_STOP_SESSION trigger actions can also | |
358 | activate and deactivate a recording session. | |
359 | <tr> | |
360 | <td>Listing | |
361 | <td> | |
362 | -# Call lttng_list_sessions(). | |
363 | ||
364 | This function sets a pointer to an array of | |
365 | \link #lttng_session recording session summaries\endlink | |
366 | and returns the number of entries. | |
367 | ||
368 | -# Access the properties of each recording session summary through | |
369 | structure members or using dedicated getters. | |
370 | ||
371 | -# When you're done with the array of recording session summaries, | |
372 | free it with <code>free()</code>. | |
373 | ||
374 | @sa \lt_man{lttng-list,1} | |
375 | <tr> | |
376 | <td>Process attribute inclusion set access | |
377 | <td>See \ref api_pais | |
378 | <tr> | |
379 | <td>Clearing | |
380 | <td>See \ref api_session_clear | |
381 | <tr> | |
382 | <td>Snapshot recording | |
383 | <td> | |
384 | See \ref api_session_snapshot | |
385 | ||
386 | The #LTTNG_ACTION_TYPE_SNAPSHOT_SESSION trigger action can also | |
387 | take a recording session snapshot. | |
388 | <tr> | |
389 | <td>Rotation | |
390 | <td> | |
391 | See \ref api_session_rotation | |
392 | ||
393 | The #LTTNG_ACTION_TYPE_ROTATE_SESSION trigger action can also | |
394 | rotate a recording session. | |
395 | <tr> | |
396 | <td>Saving and loading | |
397 | <td>See \ref api_session_save_load | |
398 | <tr> | |
399 | <td>Trace data regeneration | |
400 | <td> | |
401 | See: | |
402 | ||
403 | - lttng_regenerate_metadata() | |
404 | - lttng_regenerate_statedump() | |
405 | ||
406 | @sa \lt_man{lttng-regenerate,1} | |
407 | </table> | |
408 | ||
409 | <h1>\anchor api-session-modes Recording session modes</h1> | |
410 | ||
411 | LTTng offers four <strong><em>recording session modes</em></strong>: | |
412 | ||
413 | <table> | |
414 | <tr> | |
415 | <th>Mode | |
416 | <th>Description | |
417 | <th>Descriptor creation function(s) | |
418 | <tr> | |
419 | <td>\anchor api-session-local-mode Local | |
420 | <td> | |
421 | Write the trace data to the local file system, or do not write any | |
422 | trace data. | |
423 | <td> | |
424 | - lttng_session_descriptor_create() | |
425 | - lttng_session_descriptor_local_create() | |
426 | <tr> | |
427 | <td>\anchor api-session-net-mode Network streaming | |
428 | <td> | |
429 | Send the trace data over the network to a listening relay daemon | |
430 | (see \lt_man{lttng-relayd,8}). | |
431 | <td>lttng_session_descriptor_network_create() | |
432 | <tr> | |
433 | <td>\anchor api-session-snapshot-mode Snapshot | |
434 | <td> | |
435 | Only write the trace data to the local file system or send it to a | |
436 | listening relay daemon when LTTng | |
437 | takes a \ref api_session_snapshot "snapshot". | |
438 | ||
439 | LTTng takes a snapshot of such a recording session when: | |
440 | ||
441 | - You call lttng_snapshot_record(). | |
442 | ||
443 | - LTTng executes an #LTTNG_ACTION_TYPE_SNAPSHOT_SESSION trigger | |
444 | action. | |
445 | ||
446 | LTTng forces the | |
447 | \ref api-channel-er-loss-mode "event record loss mode" of all | |
448 | the channels of such a recording session to be | |
449 | \"\ref api-channel-overwrite-mode "overwrite"\". | |
450 | <td> | |
451 | - lttng_session_descriptor_snapshot_create() | |
452 | - lttng_session_descriptor_snapshot_local_create() | |
453 | - lttng_session_descriptor_snapshot_network_create() | |
454 | <tr> | |
455 | <td>\anchor api-session-live-mode Live | |
456 | <td> | |
457 | Send the trace data over the network to a listening relay daemon | |
458 | for live reading. | |
459 | ||
460 | An LTTng live reader (for example, | |
461 | <a href="https://babeltrace.org/">Babeltrace 2</a>) can | |
462 | connect to the same relay daemon to receive trace data while the | |
463 | recording session is active. | |
464 | <td> | |
465 | lttng_session_descriptor_live_network_create() | |
466 | </table> | |
467 | ||
468 | @sa The <em>Recording session modes</em> section of | |
469 | \lt_man{lttng-concepts,7}. | |
470 | ||
471 | <h1>\anchor api-session-url Output URL format</h1> | |
472 | ||
473 | Some functions of the \lt_api require an <strong><em>output | |
474 | URL</em></strong>. | |
475 | ||
476 | An output URL is a C string which specifies where to send trace | |
477 | data and, when LTTng connects to a relay daemon (see | |
478 | \lt_man{lttng-relayd,8}), control commands. | |
479 | ||
480 | There are three available output URL formats: | |
481 | ||
482 | <table> | |
483 | <tr> | |
484 | <th>Type | |
485 | <th>Description | |
486 | <th>Format | |
487 | <tr> | |
488 | <td>\anchor api-session-local-url Local | |
489 | <td> | |
490 | Send trace data to the local file system, without connecting to a | |
491 | relay daemon. | |
492 | ||
493 | Accepted by: | |
494 | ||
495 | - lttng_create_session() (deprecated) | |
496 | - lttng_create_session_snapshot() (deprecated) | |
497 | - lttng_snapshot_output_set_local_path() | |
498 | - lttng_save_session_attr_set_output_url() | |
499 | - lttng_load_session_attr_set_input_url() | |
500 | - lttng_load_session_attr_set_override_url() | |
501 | <td> | |
502 | <code>file://<em>TRACEDIR</em></code> | |
503 | ||
504 | <dl> | |
505 | <dt><code><em>TRACEDIR</em></code> | |
506 | <dd> | |
507 | Absolute path to the directory containing the trace data on | |
508 | the local file system. | |
509 | </dl> | |
510 | <tr> | |
511 | <td>\anchor api-session-one-port-url Remote: single port | |
512 | <td> | |
513 | Send trace data and/or control commands to a specific relay daemon | |
514 | with a specific TCP port. | |
515 | ||
516 | Accepted by: | |
517 | ||
518 | - lttng_session_descriptor_network_create() | |
519 | - lttng_session_descriptor_snapshot_network_create() | |
520 | - lttng_session_descriptor_live_network_create() | |
521 | - lttng_snapshot_output_set_network_urls() | |
522 | - lttng_snapshot_output_set_ctrl_url() | |
523 | - lttng_snapshot_output_set_data_url() | |
524 | - lttng_load_session_attr_set_override_ctrl_url() | |
525 | - lttng_load_session_attr_set_override_data_url() | |
526 | <td> | |
527 | <code><em>PROTO</em>://<em>HOST</em></code>[<code>:<em>PORT</em></code>][<code>/<em>TRACEDIR</em></code>] | |
528 | ||
529 | <dl> | |
530 | <dt><code><em>PROTO</em></code> | |
531 | <dd> | |
532 | Network protocol, amongst: | |
533 | ||
534 | <dl> | |
535 | <dt>\c net | |
536 | <dd> | |
537 | TCP over IPv4. | |
538 | ||
539 | <dt>\c net6 | |
540 | <dd> | |
541 | TCP over IPv6. | |
542 | ||
543 | <dt>\c tcp | |
544 | <dd> | |
545 | Same as <code>net</code>. | |
546 | ||
547 | <dt>\c tcp6 | |
548 | <dd> | |
549 | Same as <code>net6</code>. | |
550 | </dl> | |
551 | ||
552 | <dt><code><em>HOST</em></code> | |
553 | <dd> | |
554 | Hostname or IP address. | |
555 | ||
556 | An IPv6 address must be enclosed in square brackets (<code>[</code> | |
557 | and <code>]</code>); see | |
558 | <a href="https://www.ietf.org/rfc/rfc2732.txt">RFC 2732</a>. | |
559 | ||
560 | <dt><code><em>PORT</em></code> | |
561 | <dd> | |
562 | TCP port. | |
563 | ||
564 | If it's missing, the default control and data ports are | |
565 | respectively \lt_def_net_ctrl_port and | |
566 | \lt_def_net_data_port. | |
567 | ||
568 | <dt><code><em>TRACEDIR</em></code> | |
569 | <dd> | |
570 | Path of the directory containing the trace data on the remote | |
571 | file system. | |
572 | ||
573 | This path is relative to the base output directory of the | |
574 | LTTng relay daemon (see the <em>Output directory</em> | |
575 | section of \lt_man{lttng-relayd,8}). | |
576 | </dl> | |
577 | <tr> | |
578 | <td>\anchor api-session-two-port-url Remote: control and data ports | |
579 | <td> | |
580 | Send trace data and control commands to a specific relay daemon | |
581 | with specific TCP ports. | |
582 | ||
583 | This form is usually a shorthand for two | |
584 | \ref api-session-one-port-url "single-port output URLs" with | |
585 | specified ports. | |
586 | ||
587 | Accepted by: | |
588 | ||
589 | - lttng_create_session_snapshot() (deprecated) | |
590 | - lttng_create_session_live() (deprecated) | |
591 | - lttng_session_descriptor_network_create() | |
592 | - lttng_session_descriptor_snapshot_network_create() | |
593 | - lttng_session_descriptor_live_network_create() | |
594 | - lttng_snapshot_output_set_network_url() | |
595 | - lttng_snapshot_output_set_network_urls() | |
596 | - lttng_snapshot_output_set_ctrl_url() | |
597 | - lttng_load_session_attr_set_override_url() | |
598 | - lttng_load_session_attr_set_override_ctrl_url() | |
599 | <td> | |
600 | <code><em>PROTO</em>://<em>HOST</em>:<em>CTRLPORT</em>:<em>DATAPORT</em></code>[<code>/<em>TRACEDIR</em></code>] | |
601 | ||
602 | <dl> | |
603 | <dt><code><em>PROTO</em></code> | |
604 | <dd> | |
605 | Network protocol, amongst: | |
606 | ||
607 | <dl> | |
608 | <dt>\c net | |
609 | <dd> | |
610 | TCP over IPv4. | |
611 | ||
612 | <dt>\c net6 | |
613 | <dd> | |
614 | TCP over IPv6. | |
615 | ||
616 | <dt>\c tcp | |
617 | <dd> | |
618 | Same as <code>net</code>. | |
619 | ||
620 | <dt>\c tcp6 | |
621 | <dd> | |
622 | Same as <code>net6</code>. | |
623 | </dl> | |
624 | ||
625 | <dt><code><em>HOST</em></code> | |
626 | <dd> | |
627 | Hostname or IP address. | |
628 | ||
629 | An IPv6 address must be enclosed in square brackets (<code>[</code> | |
630 | and <code>]</code>); see | |
631 | <a href="https://www.ietf.org/rfc/rfc2732.txt">RFC 2732</a>. | |
632 | ||
633 | <dt><code><em>CTRLPORT</em></code> | |
634 | <dd> | |
635 | Control TCP port. | |
636 | ||
637 | <dt><code><em>DATAPORT</em></code> | |
638 | <dd> | |
639 | Trace data TCP port. | |
640 | ||
641 | <dt><code><em>TRACEDIR</em></code> | |
642 | <dd> | |
643 | Path of the directory containing the trace data on the remote | |
644 | file system. | |
645 | ||
646 | This path is relative to the base output directory of the | |
647 | LTTng relay daemon (see the <code>\--output</code> option of | |
648 | \lt_man{lttng-relayd,8}). | |
649 | </dl> | |
650 | </table> | |
651 | ||
652 | @defgroup api_session_descr Recording session descriptor API | |
653 | @ingroup api_session | |
654 | ||
655 | A <strong><em>recording session descriptor</em></strong> describes the | |
656 | properties of a \lt_obj_session to be (not created | |
657 | yet). | |
658 | ||
659 | To create a recording session from a recording session descriptor: | |
660 | ||
661 | -# Create a recording session descriptor | |
662 | with one of the dedicated creation functions, depending on the | |
663 | \ref api-session-modes "recording session mode": | |
664 | ||
665 | <dl> | |
666 | <dt>\ref api-session-local-mode "Local mode" | |
667 | <dd> | |
668 | One of: | |
669 | ||
670 | - lttng_session_descriptor_create() | |
671 | - lttng_session_descriptor_local_create() | |
672 | ||
673 | <dt>\ref api-session-net-mode "Network streaming mode" | |
674 | <dd> | |
675 | lttng_session_descriptor_network_create() | |
676 | ||
677 | <dt>\ref api-session-snapshot-mode "Snapshot mode" | |
678 | <dd> | |
679 | One of: | |
680 | ||
681 | - lttng_session_descriptor_snapshot_create() | |
682 | - lttng_session_descriptor_snapshot_local_create() | |
683 | - lttng_session_descriptor_snapshot_network_create() | |
684 | ||
685 | <dt>\ref api-session-live-mode "Live mode" | |
686 | <dd> | |
687 | lttng_session_descriptor_live_network_create() | |
688 | </dl> | |
689 | ||
690 | -# Call lttng_create_session_ext(), passing the recording session | |
691 | descriptor of step 1. | |
692 | ||
693 | After a successful call to this function, you can call | |
694 | lttng_session_descriptor_get_session_name() to get the name of the | |
695 | created recording session (set when creating the descriptor or | |
696 | automatically generated). | |
697 | ||
698 | -# When you're done with the recording session descriptor, destroy | |
699 | it with lttng_session_descriptor_destroy(). | |
700 | ||
701 | @defgroup api_session_destr_handle Recording session destruction handle API | |
702 | @ingroup api_session | |
703 | ||
704 | A <strong><em>recording session destruction handle</em></strong> | |
705 | represents a \lt_obj_session destruction operation. | |
706 | ||
707 | The main purposes of a recording session destruction handle is to: | |
708 | ||
709 | - Wait for the completion of the recording session | |
710 | destruction operation with | |
711 | lttng_destruction_handle_wait_for_completion() and get whether or not | |
712 | it was successful with lttng_destruction_handle_get_result(). | |
713 | ||
714 | - Get the state of any | |
715 | \ref api_session_rotation "recording session rotation" | |
716 | which the recording session destruction operation caused | |
717 | with lttng_destruction_handle_get_rotation_state(), and the location | |
718 | of its trace chunk archive with | |
719 | lttng_destruction_handle_get_archive_location(). | |
720 | ||
721 | To destroy a recording session: | |
722 | ||
723 | -# Call lttng_destroy_session_ext(), passing the name of the recording | |
724 | session to destroy. | |
725 | ||
726 | This function initiates a destruction operation, returning | |
727 | immediately. | |
728 | ||
729 | This function can set a pointer to a | |
730 | \link #lttng_destruction_handle destruction handle\endlink so that | |
731 | you can wait for the completion of the operation. Without such a | |
732 | handle, you can't know when the destruction operation completes and | |
733 | whether or not it does successfully. | |
734 | ||
735 | -# Call lttng_destruction_handle_wait_for_completion() to wait | |
736 | for the completion of the destruction operation. | |
737 | ||
738 | -# Call lttng_destruction_handle_get_result() to get whether or | |
739 | not the destruction operation successfully completed. | |
740 | ||
741 | -# <strong>If LTTng performed at least one | |
742 | \ref api_session_rotation "rotation" of the destroyed recording | |
743 | session</strong>, call lttng_destruction_handle_get_rotation_state() | |
744 | to know whether or not the last rotation was successful and | |
745 | lttng_destruction_handle_get_archive_location() to get the location | |
746 | of its trace chunk archive. | |
747 | ||
748 | -# Destroy the destruction handle with | |
749 | lttng_destruction_handle_destroy(). | |
750 | ||
751 | @defgroup api_channel Domain and channel API | |
752 | @ingroup api_session | |
753 | ||
754 | <h1>\anchor api-channel-domain Tracing domain</h1> | |
755 | ||
756 | A <strong><em>tracing domain</em></strong> identifies a type of LTTng | |
757 | tracer. | |
758 | ||
759 | A tracing domain has its own properties and features. | |
760 | ||
761 | There are currently five available tracing domains: | |
762 | ||
763 | <table> | |
764 | <tr> | |
765 | <th>Domain name | |
766 | <th>Type enumerator | |
767 | <tr> | |
768 | <td>Linux kernel | |
769 | <td>#LTTNG_DOMAIN_KERNEL | |
770 | <tr> | |
771 | <td>User space | |
772 | <td>#LTTNG_DOMAIN_UST | |
773 | <tr> | |
774 | <td><a href="https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html"><code>java.util.logging</code></a> (JUL) | |
775 | <td>#LTTNG_DOMAIN_JUL | |
776 | <tr> | |
f1f15c35 | 777 | <td><a href="https://logging.apache.org/log4j/1.x/">Apache Log4j 1.x</a> |
048f01ef | 778 | <td>#LTTNG_DOMAIN_LOG4J |
f1f15c35 MJ |
779 | <tr> |
780 | <td><a href="https://logging.apache.org/log4j/2.x/">Apache Log4j 2</a> | |
781 | <td>#LTTNG_DOMAIN_LOG4J2 | |
048f01ef PP |
782 | <tr> |
783 | <td><a href="https://docs.python.org/3/library/logging.html">Python logging</a> | |
784 | <td>#LTTNG_DOMAIN_PYTHON | |
785 | </table> | |
786 | ||
787 | A \lt_obj_channel is always part of a tracing domain. | |
788 | ||
789 | Many liblttng-ctl functions require a tracing domain type (sometimes | |
790 | within a | |
791 | \link #lttng_handle recording session handle\endlink) | |
792 | to target specific tracers or to avoid ambiguity. For example, because | |
793 | the Linux kernel and user space tracing domains support named | |
794 | tracepoints as \ref api_inst_pt "instrumentation points", you need to | |
795 | specify a tracing domain when you create a | |
796 | \lt_obj_rer with lttng_enable_event_with_exclusions() because both | |
797 | tracing domains could have LTTng tracepoints sharing the same name. | |
798 | ||
799 | @sa The <em>TRACING DOMAIN</em> section of \lt_man{lttng-concepts,7}. | |
800 | ||
801 | <h1>\anchor api-channel-channel Channel</h1> | |
802 | ||
803 | A <strong><em>channel</em></strong> is an object which is responsible | |
804 | for a set of ring buffers. | |
805 | ||
806 | Each ring buffer is divided into multiple <em>sub-buffers</em>. When a | |
807 | \lt_obj_rer matches an event, LTTng can record it to one or more | |
808 | sub-buffers of one or more channels. | |
809 | ||
810 | A channel is always associated to a \lt_obj_domain. | |
811 | The \link #LTTNG_DOMAIN_JUL <code>java.util.logging</code>\endlink, | |
f1f15c35 MJ |
812 | \link #LTTNG_DOMAIN_LOG4J Apache Log4j 1.x\endlink, |
813 | \link #LTTNG_DOMAIN_LOG4J2 Apache Log4j 2\endlink, and | |
048f01ef PP |
814 | \link #LTTNG_DOMAIN_PYTHON Python\endlink tracing |
815 | domains each have a default channel which you can't configure. | |
816 | ||
817 | Note that the some functions, like lttng_enable_event_with_exclusions(), | |
818 | can automatically create a default channel with sane defaults when no | |
819 | channel exists for the provided \lt_obj_domain. | |
820 | ||
821 | A channel owns \lt_obj_rers. | |
822 | ||
823 | @image html concepts.png "A recording session contains channels that are members of tracing domains and contain recording event rules." | |
824 | ||
825 | You can't destroy a channel. | |
826 | ||
827 | <h2>Operations</h2> | |
828 | ||
829 | The channel operations are: | |
830 | ||
831 | <table> | |
832 | <tr> | |
833 | <th>Operation | |
834 | <th>Means | |
835 | <tr> | |
836 | <td>Creation | |
837 | <td> | |
838 | -# Call lttng_channel_create() with a \lt_obj_domain summary to | |
839 | create an initial channel summary. | |
840 | ||
841 | This function calls lttng_channel_set_default_attr() to set | |
842 | the properties of the created channel summary to default values | |
843 | depending on the tracing domain summary. | |
844 | ||
845 | -# Set the properties of the channel summary of step 1 | |
846 | through direct members or with dedicated setters. | |
847 | ||
848 | See the property table below. | |
849 | ||
850 | -# Create a \link #lttng_handle recording session handle\endlink | |
851 | structure to specify the name of the recording session and the | |
852 | tracing domain of the channel to create. | |
853 | ||
854 | -# Call lttng_enable_channel() with the recording session handle | |
855 | of step 3 and the channel summary of step 1 | |
856 | o create the channel. | |
857 | ||
858 | -# Destroy the recording session handle with | |
859 | lttng_destroy_handle() and the channel summary with | |
860 | lttng_channel_destroy(). | |
861 | ||
862 | @sa \lt_man{lttng-enable-channel,1} | |
863 | <tr> | |
864 | <td>Basic property access | |
865 | <td> | |
866 | See the \ref api-channel-channel-props "property table" below. | |
867 | <tr> | |
868 | <td>\lt_obj_c_rer access | |
869 | <td> | |
870 | -# Create a \link #lttng_handle recording session handle\endlink | |
871 | with lttng_create_handle() to specify the name of the | |
872 | recording session and the summary of the | |
873 | \lt_obj_domain of the channel of which to get the recording | |
874 | event rule descriptors. | |
875 | ||
876 | -# Call lttng_list_events(), passing the recording session | |
877 | handle of step 1 and a channel name. | |
878 | ||
879 | This function sets a pointer to an array of | |
880 | \link #lttng_event recording event rule descriptors\endlink | |
881 | and returns the number of entries. | |
882 | ||
883 | -# Destroy the recording session handle of step 1 with | |
884 | lttng_destroy_handle(). | |
885 | ||
886 | -# Access the properties of each | |
887 | recording event rule descriptor through structure members or | |
888 | using dedicated getters. | |
889 | ||
890 | -# When you're done with the array of recording event rule | |
891 | descriptors, free it with <code>free()</code>. | |
892 | <tr> | |
893 | <td>Event record context field adding | |
894 | <td> | |
895 | -# Initialize a #lttng_event_context structure, setting | |
896 | its properties to describe the context field to be added. | |
897 | ||
898 | -# Create a \link #lttng_handle recording session handle\endlink | |
899 | structure to specify the name of the recording session and the | |
900 | tracing domain of the channel to create. | |
901 | ||
902 | -# Call lttng_add_context() with the recording session handle | |
903 | of step 2 and the context field descriptor of step 1, | |
904 | optionally passing the name of the channel to target. | |
905 | ||
906 | -# Destroy the recording session handle with | |
907 | lttng_destroy_handle(). | |
908 | ||
909 | @sa \lt_man{lttng-add-context,1} | |
910 | <tr> | |
911 | <td>Enabling | |
912 | <td> | |
913 | Use lttng_enable_channel(). | |
914 | ||
915 | @sa \lt_man{lttng-enable-channel,1} | |
916 | <tr> | |
917 | <td>Disabling | |
918 | <td> | |
919 | Use lttng_disable_channel(). | |
920 | ||
921 | @sa \lt_man{lttng-disable-channel,1} | |
922 | <tr> | |
923 | <td>Statistics | |
924 | <td> | |
925 | See: | |
926 | ||
927 | - lttng_channel_get_discarded_event_count() | |
928 | - lttng_channel_get_lost_packet_count() | |
929 | </table> | |
930 | ||
931 | <h2>\anchor api-channel-channel-props Properties</h2> | |
932 | ||
933 | The properties of a channel are: | |
934 | ||
935 | <table> | |
936 | <tr> | |
937 | <th>Property name | |
938 | <th>Description | |
939 | <th>Access | |
940 | <tr> | |
941 | <td>Buffering scheme | |
942 | <td> | |
943 | See \ref api-channel-buf-scheme "Buffering scheme". | |
944 | <td> | |
945 | The lttng_domain::buf_type member for the containing tracing | |
946 | domain. | |
947 | ||
948 | All the channels of a given tracing domain share the same | |
949 | buffering scheme. | |
950 | <tr> | |
951 | <td>Event record loss mode | |
952 | <td> | |
953 | See \ref api-channel-er-loss-mode "Event record loss mode". | |
954 | <td> | |
955 | The lttng_channel_attr::overwrite member. | |
956 | <tr> | |
957 | <td>Sub-buffer size | |
958 | <td> | |
959 | See \ref api-channel-sub-buf-size-count "Sub-buffer size and count". | |
960 | <td> | |
961 | The lttng_channel_attr::subbuf_size member. | |
962 | <tr> | |
963 | <td>Sub-buffer count | |
964 | <td> | |
965 | See \ref api-channel-sub-buf-size-count "Sub-buffer size and count". | |
966 | <td> | |
967 | The lttng_channel_attr::num_subbuf member. | |
968 | <tr> | |
969 | <td>Maximum trace file size | |
970 | <td> | |
971 | See \ref api-channel-max-trace-file-size-count "Maximum trace file size and count". | |
972 | <td> | |
973 | The lttng_channel_attr::tracefile_size member. | |
974 | <tr> | |
975 | <td>Maximum trace file count | |
976 | <td> | |
977 | See \ref api-channel-max-trace-file-size-count "Maximum trace file size and count". | |
978 | <td> | |
979 | The lttng_channel_attr::tracefile_count member. | |
980 | <tr> | |
981 | <td>Read timer period | |
982 | <td> | |
983 | See \ref api-channel-read-timer "Read timer". | |
984 | <td> | |
985 | The lttng_channel_attr::read_timer_interval member. | |
986 | <tr> | |
987 | <td>Switch timer period | |
988 | <td> | |
989 | See \ref api-channel-switch-timer "Switch timer". | |
990 | <td> | |
991 | The lttng_channel_attr::switch_timer_interval member. | |
992 | <tr> | |
993 | <td>Live timer period | |
994 | <td> | |
995 | See \ref api-channel-live-timer "Live timer". | |
996 | <td> | |
997 | The \lt_p{live_timer_period} parameter of | |
998 | lttng_session_descriptor_live_network_create() when you create | |
999 | the descriptor of a \ref api-session-live-mode "live" recording | |
1000 | session to contain the channel. | |
1001 | <tr> | |
1002 | <td>Monitor timer period | |
1003 | <td> | |
1004 | See \ref api-channel-monitor-timer "Monitor timer". | |
1005 | <td> | |
1006 | - lttng_channel_get_monitor_timer_interval() | |
1007 | - lttng_channel_set_monitor_timer_interval() | |
1008 | <tr> | |
1009 | <td>Output type (Linux kernel channel) | |
1010 | <td> | |
1011 | Whether to use <code>mmap()</code> or <code>splice()</code>. | |
1012 | <td> | |
1013 | The lttng_channel_attr::output member. | |
1014 | <tr> | |
1015 | <td>\anchor api-channel-blocking-timeout Blocking timeout (user space channel) | |
1016 | <td> | |
1017 | How long to block (if ever) at the instrumentation point site when | |
1018 | a sub-buffer is not available for applications executed with the | |
1019 | \c LTTNG_UST_ALLOW_BLOCKING environment variable set. | |
1020 | <td> | |
1021 | - lttng_channel_get_blocking_timeout() | |
1022 | - lttng_channel_set_blocking_timeout() | |
1023 | </table> | |
1024 | ||
1025 | All the properties above are immutable once a channel exists. | |
1026 | ||
1027 | @sa The <em>CHANNEL AND RING BUFFER</em> section of | |
1028 | \lt_man{lttng-concepts,7}. | |
1029 | ||
1030 | <h3>\anchor api-channel-buf-scheme Buffering scheme</h3> | |
1031 | ||
1032 | A channel has at least one ring buffer per CPU. LTTng always records an | |
1033 | event to the ring buffer dedicated to the CPU which emits it. | |
1034 | ||
1035 | The <strong><em>buffering scheme</em></strong> of a | |
1036 | \link #LTTNG_DOMAIN_UST user space\endlink | |
1037 | channel determines what has its own set of per-CPU | |
1038 | ring buffers, considering \lt_var{U} is the Unix user of the process | |
1039 | running liblttng-ctl: | |
1040 | ||
1041 | <dl> | |
1042 | <dt> | |
1043 | \anchor api-channel-per-user-buf | |
1044 | \link #LTTNG_BUFFER_PER_UID Per-user buffering\endlink | |
1045 | <dd> | |
1046 | Allocate one set of ring buffers (one per CPU) shared by all the | |
1047 | instrumented processes of: | |
1048 | ||
1049 | <dl> | |
1050 | <dt>If \lt_var{U} is <code>root</code> | |
1051 | <dd> | |
1052 | Each Unix user. | |
1053 | ||
1054 | @image html per-user-buffering-root.png | |
1055 | ||
1056 | <dt>Otherwise | |
1057 | <dd> | |
1058 | \lt_var{U} | |
1059 | ||
1060 | @image html per-user-buffering.png | |
1061 | </dl> | |
1062 | ||
1063 | <dt> | |
1064 | \anchor api-channel-per-proc-buf | |
1065 | \link #LTTNG_BUFFER_PER_PID Per-process buffering\endlink | |
1066 | <dd> | |
1067 | Allocate one set of ring buffers (one per CPU) for each | |
1068 | instrumented process of: | |
1069 | ||
1070 | <dl> | |
1071 | <dt>If \lt_var{U} is <code>root</code> | |
1072 | <dd> | |
1073 | All Unix users. | |
1074 | ||
1075 | @image html per-process-buffering-root.png | |
1076 | ||
1077 | <dt>Otherwise | |
1078 | <dd> | |
1079 | \lt_var{U} | |
1080 | ||
1081 | @image html per-process-buffering.png | |
1082 | </dl> | |
1083 | </dl> | |
1084 | ||
1085 | The per-process buffering scheme tends to consume more memory than the | |
1086 | per-user option because systems generally have more instrumented | |
1087 | processes than Unix users running instrumented processes. However, the | |
1088 | per-process buffering scheme ensures that one process having a high | |
1089 | event throughput won't fill all the shared sub-buffers of the same Unix | |
1090 | user, only its own. | |
1091 | ||
1092 | The buffering scheme of a Linux kernel (#LTTNG_DOMAIN_KERNEL) channel is | |
1093 | always to allocate a single set of ring buffers for the whole system | |
1094 | (#LTTNG_BUFFER_GLOBAL). This scheme is similar to the | |
1095 | \ref api-channel-per-user-buf "per-user" one, but with a single, global | |
1096 | user "running" the kernel. | |
1097 | ||
1098 | To set the buffering scheme of a channel when you create it: | |
1099 | ||
1100 | - Set the lttng_domain::buf_type member of the structure which you pass | |
1101 | within the #lttng_handle structure to lttng_enable_channel(). | |
1102 | ||
1103 | Note that, for a given \lt_obj_session, \em all | |
1104 | the channels of a given \lt_obj_domain must share the same buffering | |
1105 | scheme. | |
1106 | ||
1107 | @sa The <em>Buffering scheme</em> section of \lt_man{lttng-concepts,7}. | |
1108 | ||
1109 | <h3>\anchor api-channel-er-loss-mode Event record loss mode</h3> | |
1110 | ||
1111 | When LTTng emits an event, LTTng can record it to a specific, available | |
1112 | sub-buffer within the ring buffers of specific channels. When there's no | |
1113 | space left in a sub-buffer, the tracer marks it as consumable and | |
1114 | another, available sub-buffer starts receiving the following event | |
1115 | records. An LTTng consumer daemon eventually consumes the marked | |
1116 | sub-buffer, which returns to the available state. | |
1117 | ||
1118 | In an ideal world, sub-buffers are consumed faster than they are filled. | |
1119 | In the real world, however, all sub-buffers can be full at some point, | |
1120 | leaving no space to record the following events. | |
1121 | ||
1122 | By default, LTTng-modules and LTTng-UST are <em>non-blocking</em> | |
1123 | tracers: when there's no available sub-buffer to record an event, it's | |
1124 | acceptable to lose event records when the alternative would be to cause | |
1125 | substantial delays in the execution of the instrumented application. | |
1126 | LTTng privileges performance over integrity; it aims at perturbing the | |
1127 | instrumented application as little as possible in order to make the | |
1128 | detection of subtle race conditions and rare interrupt cascades | |
1129 | possible. | |
1130 | ||
1131 | Since LTTng 2.10, the LTTng user space tracer, LTTng-UST, supports | |
1132 | a <em>blocking mode</em>: see lttng_channel_get_blocking_timeout() and | |
1133 | lttng_channel_set_blocking_timeout(). | |
1134 | ||
1135 | When it comes to losing event records because there's no available | |
1136 | sub-buffer, or because the blocking timeout of the channel is reached, | |
1137 | the <strong><em>event record loss mode</em></strong> of the channel | |
1138 | determines what to do. The available event record loss modes are: | |
1139 | ||
1140 | <dl> | |
1141 | <dt>\anchor api-channel-discard-mode Discard mode | |
1142 | <dd> | |
1143 | Drop the newest event records until a sub-buffer becomes available. | |
1144 | ||
1145 | This is the only available mode when you specify a blocking timeout | |
1146 | with lttng_channel_set_blocking_timeout(). | |
1147 | ||
1148 | With this mode, LTTng increments a count of discarded event records | |
1149 | when it discards an event record and saves this count to the trace. | |
1150 | A trace reader can use the saved discarded event record count of the | |
1151 | trace to decide whether or not to perform some analysis even if | |
1152 | trace data is known to be missing. | |
1153 | ||
1154 | Get the number of discarded event records of a channel with | |
1155 | lttng_channel_get_discarded_event_count(). | |
1156 | ||
1157 | <dt>\anchor api-channel-overwrite-mode Overwrite mode | |
1158 | <dd> | |
1159 | Clear the sub-buffer containing the oldest event records and start | |
1160 | writing the newest event records there. | |
1161 | ||
1162 | This mode is sometimes called <em>flight recorder mode</em> because | |
1163 | it's similar to a | |
1164 | <a href="https://en.wikipedia.org/wiki/Flight_recorder">flight recorder</a>: | |
1165 | always keep a fixed amount of the latest data. It's also | |
1166 | similar to the roll mode of an oscilloscope. | |
1167 | ||
1168 | Since LTTng 2.8, with this mode, LTTng writes to a given | |
1169 | sub-buffer its sequence number within its data stream. With a | |
1170 | \ref api-session-local-mode "local", | |
1171 | \ref api-session-net-mode "network streaming", or | |
1172 | \ref api-session-live-mode "live" recording session, a trace | |
1173 | reader can use such sequence numbers to report discarded packets. A | |
1174 | trace reader can use the saved discarded sub-buffer (packet) count | |
1175 | of the trace to decide whether or not to perform some analysis even | |
1176 | if trace data is known to be missing. | |
1177 | ||
1178 | Get the number of discarded packets (sub-buffers) of a channel with | |
1179 | lttng_channel_get_lost_packet_count(). | |
1180 | ||
1181 | With this mode, LTTng doesn't write to the trace the exact number of | |
1182 | lost event records in the lost sub-buffers. | |
1183 | </dl> | |
1184 | ||
1185 | Which mechanism you should choose depends on your context: prioritize | |
1186 | the newest or the oldest event records in the ring buffer? | |
1187 | ||
1188 | Beware that, in overwrite mode, the tracer abandons a <em>whole | |
1189 | sub-buffer</em> as soon as a there's no space left for a new event | |
1190 | record, whereas in discard mode, the tracer only discards the event | |
1191 | record that doesn't fit. | |
1192 | ||
1193 | To set the event record loss mode of a channel when you create it: | |
1194 | ||
1195 | - Set the lttng_channel_attr::overwrite member of the lttng_channel::attr | |
1196 | member of the structure you pass to lttng_enable_channel(). | |
1197 | ||
1198 | There are a few ways to decrease your probability of losing event | |
1199 | records. The | |
1200 | \ref api-channel-sub-buf-size-count "Sub-buffer size and count" section | |
1201 | shows how to fine-tune the sub-buffer size and count of a channel to | |
1202 | virtually stop losing event records, though at the cost of greater | |
1203 | memory usage. | |
1204 | ||
1205 | @sa The <em>Event record loss mode</em> section of | |
1206 | \lt_man{lttng-concepts,7}. | |
1207 | ||
1208 | <h3>\anchor api-channel-sub-buf-size-count Sub-buffer size and count</h3> | |
1209 | ||
1210 | A channel has one or more ring buffer for each CPU of the target system. | |
1211 | ||
1212 | See \ref api-channel-buf-scheme "Buffering scheme" to learn how many | |
1213 | ring buffers of a given channel are dedicated to each CPU depending on | |
1214 | its buffering scheme. | |
1215 | ||
1216 | To set the size of each sub-buffer the ring buffers of a channel have | |
1217 | when you create it: | |
1218 | ||
1219 | - Set the lttng_channel_attr::subbuf_size member of the | |
1220 | lttng_channel::attr member of the structure you pass to | |
1221 | lttng_enable_channel(). | |
1222 | ||
1223 | To set the number of sub-buffers each ring buffer of a channel has | |
1224 | when you create it: | |
1225 | ||
1226 | - Set the lttng_channel_attr::num_subbuf member of the | |
1227 | lttng_channel::attr member of the structure you pass to | |
1228 | lttng_enable_channel(). | |
1229 | ||
1230 | Note that LTTng switching the current sub-buffer of a ring buffer | |
1231 | (marking a full one as consumable and switching to an available one for | |
1232 | LTTng to record the next events) introduces noticeable CPU overhead. | |
1233 | Knowing this, the following list presents a few practical situations | |
1234 | along with how to configure the sub-buffer size and count for them: | |
1235 | ||
1236 | <dl> | |
1237 | <dt>High event throughput | |
1238 | <dd> | |
1239 | In general, prefer large sub-buffers to lower the risk of losing | |
1240 | event records. | |
1241 | ||
1242 | Having larger sub-buffers also ensures a lower sub-buffer | |
1243 | \ref api-channel-switch-timer "switching frequency". | |
1244 | ||
1245 | The sub-buffer count is only meaningful if you create the channel in | |
1246 | \ref api-channel-overwrite-mode "overwrite mode": in this case, if | |
1247 | LTTng overwrites a sub-buffer, then the other sub-buffers are left | |
1248 | unaltered. | |
1249 | ||
1250 | <dt>Low event throughput | |
1251 | <dd> | |
1252 | In general, prefer smaller sub-buffers since the risk of losing | |
1253 | event records is low. | |
1254 | ||
1255 | Because LTTng emits events less frequently, the sub-buffer switching | |
1256 | frequency should remain low and therefore the overhead of the tracer | |
1257 | shouldn't be a problem. | |
1258 | ||
1259 | <dt>Low memory system | |
1260 | <dd> | |
1261 | If your target system has a low memory limit, prefer fewer first, | |
1262 | then smaller sub-buffers. | |
1263 | ||
1264 | Even if the system is limited in memory, you want to keep the | |
1265 | sub-buffers as large as possible to avoid a high sub-buffer | |
1266 | switching frequency. | |
1267 | </dl> | |
1268 | ||
1269 | Note that LTTng uses <a href="https://diamon.org/ctf/">CTF</a> as its | |
1270 | trace format, which means event record data is very compact. For | |
1271 | example, the average LTTng kernel event record weights about | |
1272 | 32 bytes. Therefore, a sub-buffer size of 1 MiB is considered | |
1273 | large. | |
1274 | ||
1275 | The previous scenarios highlight the major trade-off between a few large | |
1276 | sub-buffers and more, smaller sub-buffers: sub-buffer switching | |
1277 | frequency vs. how many event records are lost in | |
1278 | \ref api-channel-overwrite-mode "overwrite mode". | |
1279 | Assuming a constant event throughput and using the overwrite mode, the | |
1280 | two following configurations have the same ring buffer total size: | |
1281 | ||
1282 | <dl> | |
1283 | <dt>Two sub-buffers of 4 MiB each | |
1284 | <dd> | |
1285 | Expect a very low sub-buffer switching frequency, but if LTTng ever | |
1286 | needs to overwrite a sub-buffer, half of the event records so far | |
1287 | (4 MiB) are definitely lost. | |
1288 | ||
1289 | <dt>Eight sub-buffers of 1 MiB each | |
1290 | <dd> | |
1291 | Expect four times the tracer overhead of the configuration above, | |
1292 | but if LTTng needs to overwrite a sub-buffer, only the eighth of | |
1293 | event records so far (1 MiB) are definitely lost. | |
1294 | </dl> | |
1295 | ||
1296 | In \ref api-channel-discard-mode "discard mode", the sub-buffer count | |
1297 | parameter is pointless: use two sub-buffers and set their size according | |
1298 | to your requirements. | |
1299 | ||
1300 | @sa The <em>Sub-buffer size and count</em> section of | |
1301 | \lt_man{lttng-concepts,7}. | |
1302 | ||
1303 | <h3>\anchor api-channel-max-trace-file-size-count Maximum trace file size and count</h3> | |
1304 | ||
1305 | By default, trace files can grow as large as needed. | |
1306 | ||
1307 | To set the maximum size of each trace file that LTTng writes from the | |
1308 | ring buffers of a channel when you create it: | |
1309 | ||
1310 | - Set the lttng_channel_attr::tracefile_size member of the | |
1311 | lttng_channel::attr member of the structure you pass to | |
1312 | lttng_enable_channel(). | |
1313 | ||
1314 | When the size of a trace file reaches the fixed maximum size of the | |
1315 | channel, LTTng creates another file to contain the next event records. | |
1316 | LTTng appends a file count to each trace file name in this case. | |
1317 | ||
1318 | If you set the trace file size attribute when you create a channel, the | |
1319 | maximum number of trace files that LTTng creates is <em>unlimited</em> | |
1320 | by default. | |
1321 | ||
1322 | To limit the size of each trace file that LTTng writes from the | |
1323 | ring buffers of a channel when you create it: | |
1324 | ||
1325 | - Set the lttng_channel_attr::tracefile_count member of the | |
1326 | lttng_channel::attr member of the structure you pass to | |
1327 | lttng_enable_channel(). | |
1328 | ||
1329 | When the number of trace files reaches the fixed maximum count of the | |
1330 | channel, LTTng overwrites the oldest trace file. This mechanism is | |
1331 | called <em>trace file rotation</em>. | |
1332 | ||
1333 | @attention | |
1334 | @parblock | |
1335 | Even if you don't limit the trace file count, always assume that | |
1336 | LTTng manages all the trace files of the recording session. | |
1337 | ||
1338 | In other words, there's no safe way to know if LTTng still holds a | |
1339 | given trace file open with the trace file rotation feature. | |
1340 | ||
1341 | The only way to obtain an unmanaged, self-contained LTTng trace | |
1342 | before you \link lttng_destroy_session_ext() destroy the | |
1343 | recording session\endlink is with the | |
1344 | \ref api_session_rotation "recording session rotation" feature, | |
1345 | which is available since LTTng 2.11. | |
1346 | @endparblock | |
1347 | ||
1348 | @sa The <em>Maximum trace file size and count</em> section of | |
1349 | \lt_man{lttng-concepts,7}. | |
1350 | ||
1351 | <h3>\anchor api-channel-timers Timers</h3> | |
1352 | ||
1353 | Each channel can have up to four optional | |
1354 | <strong><em>timers</em></strong>: | |
1355 | ||
1356 | <dl> | |
1357 | <dt>\anchor api-channel-switch-timer Switch timer | |
1358 | <dd> | |
1359 | When this timer expires, a sub-buffer switch happens: for each ring | |
1360 | buffer of the channel, LTTng marks the current sub-buffer as | |
1361 | consumable and switches to an available one to record the next | |
1362 | events. | |
1363 | ||
1364 | A switch timer is useful to ensure that LTTng consumes and commits | |
1365 | trace data to trace files or to a distant relay daemon | |
1366 | (see \lt_man{lttng-relayd,8}) periodically in case of a low event | |
1367 | throughput. | |
1368 | ||
1369 | Such a timer is also convenient when you use | |
1370 | \ref api-channel-sub-buf-size-count "large sub-buffers" | |
1371 | to cope with a sporadic high event throughput, even if the | |
1372 | throughput is otherwise low. | |
1373 | ||
1374 | To set the period of the switch timer of a channel when you create | |
1375 | it: | |
1376 | ||
1377 | - Set the lttng_channel_attr::switch_timer_interval member of the | |
1378 | lttng_channel::attr member of the structure you pass to | |
1379 | lttng_enable_channel(). | |
1380 | ||
1381 | A channel only has a switch timer when its | |
1382 | recording session is \em not in | |
1383 | \ref api-session-live-mode "live mode". lttng_enable_channel() | |
1384 | ignores the lttng_channel_attr::switch_timer_interval member with a | |
1385 | live recording session. For a live recording session, the | |
1386 | \ref api-channel-live-timer "live timer" plays the role of the | |
1387 | switch timer. | |
1388 | ||
1389 | <dt>\anchor api-channel-live-timer Live timer | |
1390 | <dd> | |
1391 | Like the \ref api-channel-switch-timer "switch timer", but for a | |
1392 | channel which belongs to a | |
1393 | \ref api-session-live-mode "live" recording session. | |
1394 | ||
1395 | If this timer expires but there's no sub-buffer to consume, LTTng | |
1396 | sends a message with a timestamp to the connected relay daemon (see | |
1397 | \lt_man{lttng-relayd,8}) so that its live readers can progress. | |
1398 | ||
1399 | To set the period of the live timer of a channel when you create | |
1400 | its recording session: | |
1401 | ||
1402 | - Set the \lt_p{live_timer_period} parameter when you call | |
1403 | lttng_session_descriptor_live_network_create() to create a | |
1404 | live recording session descriptor to pass to | |
1405 | lttng_create_session_ext(). | |
1406 | ||
1407 | @note | |
1408 | All the channels of a live recording session share the same | |
1409 | live timer period. | |
1410 | ||
1411 | <dt>\anchor api-channel-read-timer Read timer | |
1412 | <dd> | |
1413 | When this timer expires, LTTng checks for full, consumable | |
1414 | sub-buffers. | |
1415 | ||
1416 | By default, the LTTng tracers use an asynchronous message mechanism | |
1417 | to signal a full sub-buffer so that a consumer daemon can consume | |
1418 | it. | |
1419 | ||
1420 | When such messages must be avoided, for example in real-time | |
1421 | applications, use this timer instead. | |
1422 | ||
1423 | To set the period of the read timer of a channel when you create | |
1424 | it: | |
1425 | ||
1426 | - Set the lttng_channel_attr::read_timer_interval member of the | |
1427 | lttng_channel::attr member of the structure you pass to | |
1428 | lttng_enable_channel(). | |
1429 | ||
1430 | <dt>\anchor api-channel-monitor-timer Monitor timer | |
1431 | <dd> | |
1432 | When this timer expires, the consumer daemon samples some channel | |
1433 | statistics to evaluate the following trigger conditions: | |
1434 | ||
1435 | -# The consumed buffer size of a given recording session becomes | |
1436 | greater than some value. | |
1437 | ||
1438 | -# The buffer usage of a given channel becomes greater than some | |
1439 | value. | |
1440 | ||
1441 | -# The buffer usage of a given channel becomes less than some value. | |
1442 | ||
1443 | If you disable the monitor timer of a channel \lt_var{C}: | |
1444 | ||
1445 | - The consumed buffer size value of the recording session | |
1446 | of \lt_var{C} could be wrong for trigger condition | |
1447 | type 1: the consumed buffer size of \lt_var{C} won't be | |
1448 | part of the grand total. | |
1449 | ||
1450 | - The buffer usage trigger conditions (types 2 and 3) | |
1451 | for \lt_var{C} will never be satisfied. | |
1452 | ||
1453 | See \ref api_trigger to learn more about triggers. | |
1454 | ||
1455 | To set the period of the monitor timer of a channel when you create | |
1456 | it: | |
1457 | ||
1458 | - Call lttng_channel_set_monitor_timer_interval() with the | |
1459 | #lttng_channel structure you pass to lttng_enable_channel(). | |
1460 | </dl> | |
1461 | ||
1462 | @sa The <em>Timers</em> section of \lt_man{lttng-concepts,7}. | |
1463 | ||
1464 | @defgroup api_rer Recording event rule API | |
1465 | @ingroup api_channel | |
1466 | ||
1467 | <h1>Concepts</h1> | |
1468 | ||
1469 | An <em>instrumentation point</em> is a point, within a piece of | |
1470 | software, which, when executed, creates an LTTng <em>event</em>. | |
1471 | See \ref api_inst_pt to learn how to list the available instrumentation | |
1472 | points. | |
1473 | ||
1474 | An <em>event rule</em> is a set of \ref api-rer-conds "conditions" to | |
1475 | match a set of events. | |
1476 | ||
1477 | A <strong><em>recording event rule</em></strong> is a specific type of | |
1478 | event rule of which the action is to serialize and write the matched | |
1479 | event as an <em>event record</em> to a sub-buffer of its attached | |
1480 | \lt_obj_channel. | |
1481 | ||
1482 | An event record has a \ref api-rer-er-name "name" and fields. | |
1483 | ||
1484 | When LTTng creates an event \lt_var{E}, a recording event | |
1485 | rule \lt_var{ER} is said to <em>match</em> \lt_var{E} | |
1486 | when \lt_var{E} satisfies \em all the conditions | |
1487 | of \lt_var{ER}. This concept is similar to a regular expression | |
1488 | which matches a set of strings. | |
1489 | ||
1490 | When a recording event rule matches an event, LTTng \em emits the event, | |
1491 | therefore attempting to record it. | |
1492 | ||
1493 | @attention | |
1494 | @parblock | |
1495 | The event creation and emission processes are \em documentation | |
1496 | concepts to help understand the journey from an instrumentation | |
1497 | point to an event record. | |
1498 | ||
1499 | The actual creation of an event can be costly because LTTng needs to | |
1500 | evaluate the arguments of the instrumentation point. | |
1501 | ||
1502 | In practice, LTTng implements various optimizations for the | |
1503 | \link #LTTNG_DOMAIN_KERNEL Linux kernel\endlink and | |
1504 | \link #LTTNG_DOMAIN_UST user space\endlink \lt_obj_domains | |
1505 | to avoid actually creating an event when the tracer knows, thanks to | |
1506 | properties which are independent from the event payload and current | |
1507 | \link #lttng_event_context_type context\endlink, that it would never | |
1508 | emit such an event. Those properties are: | |
1509 | ||
1510 | - The \ref api-rer-conds-inst-pt-type "instrumentation point type". | |
1511 | ||
1512 | - The \ref api-rer-conds-event-name "instrumentation point name" (or | |
1513 | event name). | |
1514 | ||
1515 | - The \ref api-rer-conds-ll "instrumentation point log level". | |
1516 | ||
1517 | - The \link lttng_event::enabled status\endlink (enabled or | |
1518 | disabled) of the rule itself. | |
1519 | ||
1520 | - The \link lttng_channel::enabled status\endlink (enabled or | |
1521 | disabled) of the \lt_obj_channel containing the rule. | |
1522 | ||
1523 | - The \link lttng_session::enabled activity\endlink (started or | |
1524 | stopped) of the \lt_obj_session containing the rule. | |
1525 | ||
1526 | - Whether or not the process for which LTTng would create the event | |
1527 | is \ref api_pais "allowed to record events". | |
1528 | ||
1529 | In other words: if, for a given instrumentation point \lt_var{IP}, | |
1530 | the LTTng tracer knows that it would never emit an event, | |
1531 | executing \lt_var{IP} represents a simple boolean variable check | |
1532 | and, for a \link #LTTNG_DOMAIN_KERNEL Linux kernel\endlink | |
1533 | \lt_obj_rer, a few current process attribute checks. | |
1534 | @endparblock | |
1535 | ||
1536 | You always attach a recording event rule to a | |
1537 | \lt_obj_channel, which belongs to | |
1538 | a \lt_obj_session, when you | |
1539 | \link lttng_enable_event_with_exclusions() create it\endlink. | |
1540 | A channel owns recording event rules. | |
1541 | ||
1542 | When multiple matching recording event rules are attached to the same | |
1543 | channel, LTTng attempts to serialize and record the matched event | |
1544 | <em>once</em>. | |
1545 | ||
1546 | @image html event-rule.png "Logical path from an instrumentation point to an event record." | |
1547 | ||
1548 | As of LTTng-tools \lt_version_maj_min, you cannot remove a | |
1549 | recording event rule: it exists as long as its \lt_obj_session exists. | |
1550 | ||
1551 | <h1>Operations</h1> | |
1552 | ||
1553 | The recording event rule operations are: | |
1554 | ||
1555 | <table> | |
1556 | <tr> | |
1557 | <th>Operation | |
1558 | <th>Means | |
1559 | <tr> | |
1560 | <td>Creation | |
1561 | <td> | |
1562 | -# Call lttng_event_create() to create an initial | |
1563 | \link #lttng_event recording event rule descriptor\endlink. | |
1564 | ||
1565 | -# Set the properties of the recording event rule descriptor of | |
1566 | step 1 through direct members or with dedicated setters. | |
1567 | ||
1568 | See the property table below. | |
1569 | ||
1570 | -# Create a \link #lttng_handle recording session handle\endlink | |
1571 | structure to specify the name of the recording session and the | |
1572 | tracing domain of the recording event rule to create. | |
1573 | ||
1574 | -# Call lttng_enable_event_with_exclusions() with the recording | |
1575 | session handle of step 3, the recording event rule | |
1576 | descriptor of step 1, the name of a | |
1577 | \lt_obj_channel to which to attach the | |
1578 | created recording event rule, and, depending on the selected | |
1579 | function, other properties to create the rule. | |
1580 | ||
1581 | -# Destroy the recording session handle with | |
1582 | lttng_destroy_handle() and the recording event rule descriptor | |
1583 | with lttng_event_destroy(). | |
1584 | ||
1585 | @sa \lt_man{lttng-enable-event,1} | |
1586 | <tr> | |
1587 | <td>Property access | |
1588 | <td> | |
1589 | See: | |
1590 | ||
1591 | - The members of #lttng_event | |
1592 | - lttng_event_get_userspace_probe_location() | |
1593 | - lttng_event_set_userspace_probe_location() | |
1594 | - lttng_event_get_filter_expression() | |
1595 | - lttng_event_get_exclusion_name_count() | |
1596 | - lttng_event_get_exclusion_name() | |
1597 | ||
1598 | @sa \ref api-rer-conds "Recording event rule conditions". | |
1599 | <tr> | |
1600 | <td>Enabling | |
1601 | <td> | |
1602 | With an #lttng_event instance which comes from | |
1603 | lttng_list_events(), use lttng_enable_event(). | |
1604 | ||
1605 | Otherwise, use lttng_enable_event_with_exclusions(). | |
1606 | ||
1607 | @sa \lt_man{lttng-enable-event,1} | |
1608 | <tr> | |
1609 | <td>Disabling | |
1610 | <td> | |
1611 | Use lttng_disable_event() or lttng_disable_event_ext(). | |
1612 | ||
1613 | @sa \lt_man{lttng-disable-event,1} | |
1614 | </table> | |
1615 | ||
1616 | <h1>\anchor api-rer-conds Recording event rule conditions</h1> | |
1617 | ||
1618 | For LTTng to emit and record an event \lt_var{E}, \lt_var{E} | |
1619 | must satisfy \em all the conditions of a recording event | |
1620 | rule \lt_var{ER}, that is: | |
1621 | ||
1622 | <dl> | |
1623 | <dt>Explicit conditions | |
1624 | <dd> | |
1625 | You set the following conditions when you | |
1626 | \link lttng_enable_event_with_exclusions() create\endlink | |
1627 | \lt_var{ER} from some | |
1628 | \link #lttng_event recording event rule descriptor\endlink | |
1629 | \c event_rule (#lttng_event). | |
1630 | ||
1631 | <table> | |
1632 | <tr> | |
1633 | <th>Name | |
1634 | <th>Description | |
1635 | <tr> | |
1636 | <td> | |
1637 | \anchor api-rer-conds-inst-pt-type | |
1638 | \ref api-rer-conds-inst-pt-type "Instrumentation point type" | |
1639 | <td> | |
1640 | \lt_var{E} satisfies the instrumentation point type condition | |
1641 | of \lt_var{ER} if the instrumentation point from which LTTng | |
1642 | creates \lt_var{E} is, depending on the | |
1643 | \lt_obj_domain which contains \lt_var{ER}: | |
1644 | ||
1645 | <dl> | |
1646 | <dt>#LTTNG_DOMAIN_KERNEL | |
1647 | <dd> | |
1648 | Depending on | |
1649 | \link lttng_event::type <code>event_rule.type</code>\endlink: | |
1650 | ||
1651 | <dl> | |
1652 | <dt>#LTTNG_EVENT_TRACEPOINT | |
1653 | <dd> | |
1654 | An LTTng kernel tracepoint, that is, a statically | |
1655 | defined point in the source code of the kernel image | |
1656 | or of a kernel module with LTTng kernel tracer macros. | |
1657 | ||
1658 | @sa lttng_list_tracepoints() | |
1659 | ||
1660 | <dt>#LTTNG_EVENT_SYSCALL | |
1661 | <dd> | |
1662 | The entry and exit of a Linux kernel system call. | |
1663 | ||
1664 | @sa lttng_list_syscalls() | |
1665 | ||
1666 | <dt>#LTTNG_EVENT_PROBE | |
1667 | <dd> | |
1668 | A Linux | |
1669 | <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kprobe</a>, | |
1670 | that is, a single probe dynamically placed in the | |
1671 | compiled kernel code. | |
1672 | ||
1673 | \link lttng_event::lttng_event_attr_u::probe | |
1674 | <code>event_rule.attr.probe</code>\endlink | |
1675 | indicates the kprobe location, | |
1676 | while \link lttng_event::name | |
1677 | <code>event_rule.name</code>\endlink | |
1678 | is the name of the created kprobe instrumentation | |
1679 | point (future event name). | |
1680 | ||
1681 | The payload of a Linux kprobe event is empty. | |
1682 | ||
1683 | <dt>#LTTNG_EVENT_FUNCTION | |
1684 | <dd> | |
1685 | A Linux | |
1686 | <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kretprobe</a>, | |
1687 | that is, two probes dynamically placed at the entry | |
1688 | and exit of a function in the compiled kernel code. | |
1689 | ||
1690 | \link lttng_event::lttng_event_attr_u::probe | |
1691 | <code>event_rule.attr.probe</code>\endlink | |
1692 | indicates the kretprobe location, | |
1693 | while \link lttng_event::name | |
1694 | <code>event_rule.name</code>\endlink | |
1695 | is the name of the created kretprobe instrumentation | |
1696 | point (future event name). | |
1697 | ||
1698 | The payload of a Linux kretprobe event is empty. | |
1699 | ||
1700 | <dt>#LTTNG_EVENT_USERSPACE_PROBE | |
1701 | <dd> | |
1702 | A Linux | |
1703 | <a href="https://lwn.net/Articles/499190/">uprobe</a>, | |
1704 | that is, a single probe dynamically placed at the | |
1705 | entry of a compiled user space application/library | |
1706 | function through the kernel. | |
1707 | ||
1708 | Set and get the location of the uprobe with | |
1709 | lttng_event_set_userspace_probe_location() and | |
1710 | lttng_event_get_userspace_probe_location(). | |
1711 | ||
1712 | \link lttng_event::name <code>event_rule.name</code>\endlink | |
1713 | is the name of the created uprobe instrumentation | |
1714 | point (future event name). | |
1715 | ||
1716 | The payload of a Linux uprobe event is empty. | |
1717 | </dl> | |
1718 | ||
1719 | <dt>#LTTNG_DOMAIN_UST | |
1720 | <dd> | |
1721 | An LTTng user space tracepoint, that is, a statically | |
1722 | defined point in the source code of a C/C++ | |
1723 | application/library with LTTng user space tracer macros. | |
1724 | ||
1725 | \link lttng_event::type <code>event_rule.type</code>\endlink | |
1726 | must be #LTTNG_EVENT_TRACEPOINT. | |
1727 | ||
1728 | @sa lttng_list_tracepoints() | |
1729 | ||
1730 | <dt>#LTTNG_DOMAIN_JUL | |
1731 | <dt>#LTTNG_DOMAIN_LOG4J | |
1732 | <dt>#LTTNG_DOMAIN_PYTHON | |
1733 | <dd> | |
1734 | A Java/Python logging statement. | |
1735 | ||
1736 | \link lttng_event::type <code>event_rule.type</code>\endlink | |
1737 | must be #LTTNG_EVENT_TRACEPOINT. | |
1738 | ||
1739 | @sa lttng_list_tracepoints() | |
1740 | </dl> | |
1741 | <tr> | |
1742 | <td> | |
1743 | \anchor api-rer-conds-event-name | |
1744 | \ref api-rer-conds-event-name "Event name" | |
1745 | <td> | |
1746 | An event \lt_var{E} satisfies the event name condition | |
1747 | of \lt_var{ER} if the two following statements are | |
1748 | \b true: | |
1749 | ||
1750 | - \link lttng_event::name <code>event_rule.name</code>\endlink | |
1751 | matches, depending on | |
1752 | \link lttng_event::type <code>event_rule.type</code>\endlink | |
1753 | (see \ref api-rer-conds-inst-pt-type "Instrumentation point type" | |
1754 | above): | |
1755 | ||
1756 | <dl> | |
1757 | <dt>#LTTNG_EVENT_TRACEPOINT | |
1758 | <dd> | |
1759 | The full name of the LTTng tracepoint or Java/Python | |
1760 | logger from which LTTng creates \lt_var{E}. | |
1761 | ||
1762 | Note that the full name of a | |
1763 | \link #LTTNG_DOMAIN_UST user space\endlink tracepoint is | |
1764 | <code><em>PROVIDER</em>:<em>NAME</em></code>, where | |
1765 | <code><em>PROVIDER</em></code> is the tracepoint | |
1766 | provider name and <code><em>NAME</em></code> is the | |
1767 | tracepoint name. | |
1768 | ||
1769 | <dt>#LTTNG_EVENT_SYSCALL | |
1770 | <dd> | |
1771 | The name of the system call, without any | |
1772 | <code>sys_</code> prefix, from which LTTng | |
1773 | creates \lt_var{E}. | |
1774 | </dl> | |
1775 | ||
1776 | @sa \ref api-rer-er-name "Event record name". | |
1777 | ||
1778 | - If the \lt_obj_domain | |
1779 | containing \lt_var{ER} is #LTTNG_DOMAIN_UST: | |
1780 | none of the event name exclusion patterns of | |
1781 | \c event_rule matches the full name of the user | |
1782 | space tracepoint from which LTTng creates \lt_var{E}. | |
1783 | ||
1784 | Set the event name exclusion patterns of | |
1785 | \c event_rule when you call | |
1786 | lttng_enable_event_with_exclusions(). | |
1787 | ||
1788 | Get the event name exclusion patterns of | |
1789 | a recording event rule descriptor with | |
1790 | lttng_event_get_exclusion_name_count() and | |
1791 | lttng_event_get_exclusion_name(). | |
1792 | ||
1793 | This condition is only meaningful when | |
1794 | \link lttng_event::type <code>event_rule.type</code>\endlink | |
1795 | is #LTTNG_EVENT_TRACEPOINT or | |
1796 | #LTTNG_EVENT_SYSCALL: it's always satisfied for the other | |
1797 | \ref api-rer-conds-inst-pt-type "instrumentation point types". | |
1798 | ||
1799 | In all cases, | |
1800 | \link lttng_event::name <code>event_rule.name</code>\endlink | |
1801 | and the event name exclusion patterns of | |
1802 | \c event_rule are <em>globbing patterns</em>: the | |
1803 | <code>*</code> character means "match anything". To match a | |
1804 | literal <code>*</code> character, use <code>\\*</code>. | |
1805 | <tr> | |
1806 | <td> | |
1807 | \anchor api-rer-conds-ll | |
1808 | \ref api-rer-conds-ll "Instrumentation point log level" | |
1809 | <td> | |
1810 | An event \lt_var{E} satisfies the instrumentation point | |
1811 | log level condition of \lt_var{ER} if, depending on | |
1812 | \link lttng_event::loglevel_type <code>event_rule.loglevel_type</code>\endlink, | |
1813 | the log level of the LTTng user space tracepoint or | |
1814 | logging statement from which LTTng creates \lt_var{E} | |
1815 | is: | |
1816 | ||
1817 | <dl> | |
1818 | <dt>#LTTNG_EVENT_LOGLEVEL_ALL | |
1819 | <dd> | |
1820 | Anything (the condition is always satisfied). | |
1821 | ||
1822 | <dt>#LTTNG_EVENT_LOGLEVEL_RANGE | |
1823 | <dd> | |
1824 | At least as severe as | |
1825 | \link lttng_event::loglevel <code>event_rule.loglevel</code>\endlink. | |
1826 | ||
1827 | <dt>#LTTNG_EVENT_LOGLEVEL_SINGLE | |
1828 | <dd> | |
1829 | Exactly | |
1830 | \link lttng_event::loglevel <code>event_rule.loglevel</code>\endlink. | |
1831 | </dl> | |
1832 | ||
1833 | This condition is only meaningful when the \lt_obj_domain | |
1834 | containing \lt_var{ER} is \em not #LTTNG_DOMAIN_KERNEL: | |
1835 | it's always satisfied for #LTTNG_DOMAIN_KERNEL. | |
1836 | <tr> | |
1837 | <td> | |
1838 | \anchor api-rer-conds-filter | |
1839 | \ref api-rer-conds-filter "Event payload and context filter" | |
1840 | <td> | |
1841 | An event \lt_var{E} satisfies the event payload and | |
1842 | context filter condition of \lt_var{ER} if | |
1843 | \c event_rule has no filter expression or if its filter | |
1844 | expression \lt_var{EXPR} evaluates to \b true | |
1845 | when LTTng creates \lt_var{E}. | |
1846 | ||
1847 | This condition is only meaningful when: | |
1848 | ||
1849 | - The \lt_obj_domain containing \lt_var{ER} is | |
1850 | #LTTNG_DOMAIN_KERNEL or #LTTNG_DOMAIN_UST: it's always | |
1851 | satisfied for the other tracing domains. | |
1852 | ||
1853 | - \link lttng_event::type <code>event_rule.type</code>\endlink | |
1854 | is #LTTNG_EVENT_TRACEPOINT or #LTTNG_EVENT_SYSCALL: | |
1855 | it's always satisfied for the other | |
1856 | \ref api-rer-conds-inst-pt-type "instrumentation point types". | |
1857 | ||
1858 | Set the event payload and context filter expression of | |
1859 | \c event_rule when you call | |
1860 | lttng_enable_event_with_exclusions(). | |
1861 | ||
1862 | Get the event payload and context filter expression of | |
1863 | a recording event rule descriptor with | |
1864 | lttng_event_get_filter_expression(). | |
1865 | ||
1866 | \lt_var{EXPR} can contain references to the payload fields | |
1867 | of \lt_var{E} and to the current | |
1868 | \link #lttng_event_context_type context\endlink fields. | |
1869 | ||
1870 | The expected syntax of \lt_var{EXPR} is similar to the syntax | |
1871 | of a C language conditional expression (an expression | |
1872 | which an \c if statement can evaluate), but there are a few | |
1873 | differences: | |
1874 | ||
1875 | - A <code><em>NAME</em></code> expression identifies an event | |
1876 | payload field named <code><em>NAME</em></code> (a | |
1877 | C identifier). | |
1878 | ||
1879 | Use the C language dot and square bracket notations to | |
1880 | access nested structure and array/sequence fields. You can | |
1881 | only use a constant, positive integer number within square | |
1882 | brackets. If the index is out of bounds, \lt_var{EXPR} is | |
1883 | \b false. | |
1884 | ||
1885 | The value of an enumeration field is an integer. | |
1886 | ||
1887 | When a field expression doesn't exist, \lt_var{EXPR} is | |
1888 | \b false. | |
1889 | ||
1890 | Examples: <code>my_field</code>, <code>target_cpu</code>, | |
1891 | <code>seq[7]</code>, <code>msg.user[1].data[2][17]</code>. | |
1892 | ||
1893 | - A <code>$ctx.<em>TYPE</em></code> expression identifies the | |
1894 | statically-known context field having the type | |
1895 | <code><em>TYPE</em></code> (a C identifier). | |
1896 | ||
1897 | When a field expression doesn't exist, \lt_var{EXPR} is \b | |
1898 | false. | |
1899 | ||
1900 | Examples: <code>$ctx.prio</code>, | |
1901 | <code>$ctx.preemptible</code>, | |
1902 | <code>$ctx.perf:cpu:stalled-cycles-frontend</code>. | |
1903 | ||
1904 | - A <code>$app.<em>PROVIDER</em>:<em>TYPE</em></code> | |
1905 | expression identifies the application-specific context field | |
1906 | having the type <code><em>TYPE</em></code> (a | |
1907 | C identifier) from the provider | |
1908 | <code><em>PROVIDER</em></code> (a C identifier). | |
1909 | ||
1910 | When a field expression doesn't exist, \lt_var{EXPR} is \b | |
1911 | false. | |
1912 | ||
1913 | Example: <code>$app.server:cur_user</code>. | |
1914 | ||
1915 | - Compare strings, either string fields or string literals | |
1916 | (double-quoted), with the <code>==</code> and | |
1917 | <code>!=</code> operators. | |
1918 | ||
1919 | When comparing to a string literal, the <code>*</code> | |
1920 | character means "match anything". To match a literal | |
1921 | <code>*</code> character, use <code>\\*</code>. | |
1922 | ||
1923 | Examples: <code>my_field == "user34"</code>, | |
1924 | <code>my_field == my_other_field</code>, | |
1925 | <code>my_field == "192.168.*"</code>. | |
1926 | ||
1927 | - The | |
1928 | <a href="https://en.wikipedia.org/wiki/Order_of_operations">precedence table</a> | |
1929 | of the operators which are supported in | |
1930 | \lt_var{EXPR} is as follows. In this table, the highest | |
1931 | precedence is 1: | |
1932 | ||
1933 | <table> | |
1934 | <tr> | |
1935 | <th>Precedence | |
1936 | <th>Operator | |
1937 | <th>Description | |
1938 | <th>Associativity | |
1939 | <tr> | |
1940 | <td>1 | |
1941 | <td><code>-</code> | |
1942 | <td>Unary minus | |
1943 | <td>Right-to-left | |
1944 | <tr> | |
1945 | <td>1 | |
1946 | <td><code>+</code> | |
1947 | <td>Unary plus | |
1948 | <td>Right-to-left | |
1949 | <tr> | |
1950 | <td>1 | |
1951 | <td><code>!</code> | |
1952 | <td>Logical NOT | |
1953 | <td>Right-to-left | |
1954 | <tr> | |
1955 | <td>1 | |
1956 | <td><code>~</code> | |
1957 | <td>Bitwise NOT | |
1958 | <td>Right-to-left | |
1959 | <tr> | |
1960 | <td>2 | |
1961 | <td><code><<</code> | |
1962 | <td>Bitwise left shift | |
1963 | <td>Left-to-right | |
1964 | <tr> | |
1965 | <td>2 | |
1966 | <td><code>>></code> | |
1967 | <td>Bitwise right shift | |
1968 | <td>Left-to-right | |
1969 | <tr> | |
1970 | <td>3 | |
1971 | <td><code>&</code> | |
1972 | <td>Bitwise AND | |
1973 | <td>Left-to-right | |
1974 | <tr> | |
1975 | <td>4 | |
1976 | <td><code>^</code> | |
1977 | <td>Bitwise XOR | |
1978 | <td>Left-to-right | |
1979 | <tr> | |
1980 | <td>5 | |
1981 | <td><code>|</code> | |
1982 | <td>Bitwise OR | |
1983 | <td>Left-to-right | |
1984 | <tr> | |
1985 | <td>6 | |
1986 | <td><code><</code> | |
1987 | <td>Less than | |
1988 | <td>Left-to-right | |
1989 | <tr> | |
1990 | <td>6 | |
1991 | <td><code><=</code> | |
1992 | <td>Less than or equal to | |
1993 | <td>Left-to-right | |
1994 | <tr> | |
1995 | <td>6 | |
1996 | <td><code>></code> | |
1997 | <td>Greater than | |
1998 | <td>Left-to-right | |
1999 | <tr> | |
2000 | <td>6 | |
2001 | <td><code>>=</code> | |
2002 | <td>Greater than or equal to | |
2003 | <td>Left-to-right | |
2004 | <tr> | |
2005 | <td>7 | |
2006 | <td><code>==</code> | |
2007 | <td>Equal to | |
2008 | <td>Left-to-right | |
2009 | <tr> | |
2010 | <td>7 | |
2011 | <td><code>!=</code> | |
2012 | <td>Not equal to | |
2013 | <td>Left-to-right | |
2014 | <tr> | |
2015 | <td>8 | |
2016 | <td><code>&&</code> | |
2017 | <td>Logical AND | |
2018 | <td>Left-to-right | |
2019 | <tr> | |
2020 | <td>9 | |
2021 | <td><code>||</code> | |
2022 | <td>Logical OR | |
2023 | <td>Left-to-right | |
2024 | </table> | |
2025 | ||
2026 | Parentheses are supported to bypass the default order. | |
2027 | ||
2028 | @attention | |
2029 | Unlike the C language, the bitwise AND and OR | |
2030 | operators (<code>&</code> and <code>|</code>) in | |
2031 | \lt_var{EXPR} take precedence over relational | |
2032 | operators (<code><<</code>, <code><=</code>, | |
2033 | <code>></code>, <code>>=</code>, <code>==</code>, | |
2034 | and <code>!=</code>). This means the expression | |
2035 | <code>2 & 2 == 2</code> | |
2036 | is \b true while the equivalent C expression | |
2037 | is \b false. | |
2038 | ||
2039 | The arithmetic operators are :not: supported. | |
2040 | ||
2041 | LTTng first casts all integer constants and fields to signed | |
2042 | 64-bit integers. The representation of negative integers is | |
2043 | two's complement. This means that, for example, the signed | |
2044 | 8-bit integer field 0xff (-1) becomes 0xffffffffffffffff | |
2045 | (still -1) once casted. | |
2046 | ||
2047 | Before a bitwise operator is applied, LTTng casts all its | |
2048 | operands to unsigned 64-bit integers, and then casts the | |
2049 | result back to a signed 64-bit integer. For the bitwise NOT | |
2050 | operator, it's the equivalent of this C expression: | |
2051 | ||
2052 | @code | |
2053 | (int64_t) ~((uint64_t) val) | |
2054 | @endcode | |
2055 | ||
2056 | For the binary bitwise operators, it's the equivalent of those | |
2057 | C expressions: | |
2058 | ||
2059 | @code | |
2060 | (int64_t) ((uint64_t) lhs >> (uint64_t) rhs) | |
2061 | (int64_t) ((uint64_t) lhs << (uint64_t) rhs) | |
2062 | (int64_t) ((uint64_t) lhs & (uint64_t) rhs) | |
2063 | (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs) | |
2064 | (int64_t) ((uint64_t) lhs | (uint64_t) rhs) | |
2065 | @endcode | |
2066 | ||
2067 | If the right-hand side of a bitwise shift operator | |
2068 | (<code><<</code> and <code>>></code>) is not in | |
2069 | the [0, 63] range, then \lt_var{EXPR} is \b false. | |
2070 | ||
2071 | @note | |
2072 | See the \ref api_pais to allow or disallow processes to | |
2073 | record LTTng events based on their attributes | |
2074 | instead of using equivalent statically-known context | |
2075 | fields in \lt_var{EXPR} like <code>$ctx.pid</code>. | |
2076 | The former method is much more efficient. | |
2077 | ||
2078 | \lt_var{EXPR} examples: | |
2079 | ||
2080 | @code{.unparsed} | |
2081 | msg_id == 23 && size >= 2048 | |
2082 | @endcode | |
2083 | ||
2084 | @code{.unparsed} | |
2085 | $ctx.procname == "lttng*" && (!flag || poel < 34) | |
2086 | @endcode | |
2087 | ||
2088 | @code{.unparsed} | |
2089 | $app.my_provider:my_context == 17.34e9 || some_enum >= 14 | |
2090 | @endcode | |
2091 | ||
2092 | @code{.unparsed} | |
2093 | $ctx.cpu_id == 2 && filename != "*.log" | |
2094 | @endcode | |
2095 | ||
2096 | @code{.unparsed} | |
2097 | eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234 | |
2098 | @endcode | |
2099 | </table> | |
2100 | ||
2101 | <dt>Implicit conditions | |
2102 | <dd> | |
2103 | - \lt_var{ER} itself is \link lttng_event::enabled enabled\endlink. | |
2104 | ||
2105 | A recording event rule is enabled on | |
2106 | \link lttng_enable_event_with_exclusions() creation\endlink. | |
2107 | ||
2108 | @sa lttng_enable_event() -- | |
2109 | Creates or enables a recording event rule. | |
2110 | @sa lttng_disable_event_ext() -- | |
2111 | Disables a recording event rule. | |
2112 | ||
2113 | - The \lt_obj_channel which contains \lt_var{ER} is | |
2114 | \link lttng_channel::enabled enabled\endlink. | |
2115 | ||
2116 | A channel is enabled on | |
2117 | \link lttng_enable_channel() creation\endlink. | |
2118 | ||
2119 | @sa lttng_enable_channel() -- | |
2120 | Creates or enables a channel. | |
2121 | @sa lttng_disable_channel() -- | |
2122 | Disables a channel. | |
2123 | ||
2124 | - The \lt_obj_session which contains \lt_var{ER} is | |
2125 | \link lttng_session::enabled active\endlink (started). | |
2126 | ||
2127 | A recording session is inactive (stopped) on | |
2128 | \link lttng_create_session_ext() creation\endlink. | |
2129 | ||
2130 | @sa lttng_start_tracing() -- | |
2131 | Starts a recording session. | |
2132 | @sa lttng_stop_tracing() -- | |
2133 | Stops a recording session. | |
2134 | ||
2135 | - The process for which LTTng creates \lt_var{E} is | |
2136 | \ref api_pais "allowed to record events". | |
2137 | ||
2138 | All processes are allowed to record events on recording session | |
2139 | \link lttng_create_session_ext() creation\endlink. | |
2140 | </dl> | |
2141 | ||
2142 | <h1>\anchor api-rer-er-name Event record name</h1> | |
2143 | ||
2144 | When LTTng records an event \lt_var{E}, the resulting event record | |
2145 | has a name which depends on the | |
2146 | \ref api-rer-conds-inst-pt-type "instrumentation point type condition" | |
2147 | of the recording event rule \lt_var{ER} which matched \lt_var{E} | |
2148 | as well as on the \lt_obj_domain which contains \lt_var{ER}: | |
2149 | ||
2150 | <table> | |
2151 | <tr> | |
2152 | <th>Tracing domain | |
2153 | <th>Instrumentation point type | |
2154 | <th>Event record name | |
2155 | <tr> | |
2156 | <td>#LTTNG_DOMAIN_KERNEL or #LTTNG_DOMAIN_UST | |
2157 | <td>#LTTNG_EVENT_TRACEPOINT | |
2158 | <td> | |
2159 | Full name of the tracepoint from which LTTng creates \lt_var{E}. | |
2160 | ||
2161 | Note that the full name of a | |
2162 | \link #LTTNG_DOMAIN_UST user space\endlink tracepoint is | |
2163 | <code><em>PROVIDER</em>:<em>NAME</em></code>, where | |
2164 | <code><em>PROVIDER</em></code> is the tracepoint provider name and | |
2165 | <code><em>NAME</em></code> is the tracepoint name. | |
2166 | <tr> | |
2167 | <td>#LTTNG_DOMAIN_JUL | |
2168 | <td>#LTTNG_EVENT_TRACEPOINT | |
2169 | <td> | |
2170 | <code>lttng_jul:event</code> | |
2171 | ||
2172 | Such an event record has a string field <code>logger_name</code> | |
2173 | which contains the name of the <code>java.util.logging</code> | |
2174 | logger from which LTTng creates \lt_var{E}. | |
2175 | <tr> | |
2176 | <td>#LTTNG_DOMAIN_LOG4J | |
2177 | <td>#LTTNG_EVENT_TRACEPOINT | |
2178 | <td> | |
2179 | <code>lttng_log4j:event</code> | |
2180 | ||
2181 | Such an event record has a string field <code>logger_name</code> | |
f1f15c35 MJ |
2182 | which contains the name of the Apache Log4j 1.x logger from which |
2183 | LTTng creates \lt_var{E}. | |
2184 | <tr> | |
2185 | <td>#LTTNG_DOMAIN_LOG4J2 | |
2186 | <td>#LTTNG_EVENT_TRACEPOINT | |
2187 | <td> | |
2188 | <code>lttng_log4j2:event</code> | |
2189 | ||
2190 | Such an event record has a string field <code>logger_name</code> | |
2191 | which contains the name of the Apache Log4j 2 logger from which | |
048f01ef PP |
2192 | LTTng creates \lt_var{E}. |
2193 | <tr> | |
2194 | <td>#LTTNG_DOMAIN_PYTHON | |
2195 | <td>#LTTNG_EVENT_TRACEPOINT | |
2196 | <td> | |
2197 | <code>lttng_python:event</code> | |
2198 | ||
2199 | Such an event record has a string field <code>logger_name</code> | |
2200 | which contains the name of the Python logger from which LTTng | |
2201 | creates \lt_var{E}. | |
2202 | <tr> | |
2203 | <td>#LTTNG_DOMAIN_KERNEL | |
2204 | <td>#LTTNG_EVENT_SYSCALL | |
2205 | <td> | |
2206 | Location: | |
2207 | ||
2208 | <dl> | |
2209 | <dt>Entry | |
2210 | <dd> | |
2211 | <code>syscall_entry_<em>NAME</em></code>, where | |
2212 | <code><em>NAME</em></code> is the name of the system call from | |
2213 | which LTTng creates \lt_var{E}, without any | |
2214 | <code>sys_</code> prefix. | |
2215 | ||
2216 | <dt>Exit | |
2217 | <dd> | |
2218 | <code>syscall_exit_<em>NAME</em></code>, where | |
2219 | <code><em>NAME</em></code> is the name of the system call from | |
2220 | which LTTng creates \lt_var{E}, without any | |
2221 | <code>sys_</code> prefix. | |
2222 | </dl> | |
2223 | <tr> | |
2224 | <td>#LTTNG_DOMAIN_KERNEL | |
2225 | <td>#LTTNG_EVENT_PROBE or #LTTNG_EVENT_USERSPACE_PROBE | |
2226 | <td> | |
2227 | The lttng_event::name member of the | |
2228 | descriptor you used to create \lt_var{ER} with | |
2229 | lttng_enable_event_with_exclusions(). | |
2230 | <tr> | |
2231 | <td>#LTTNG_DOMAIN_KERNEL | |
2232 | <td>#LTTNG_EVENT_FUNCTION | |
2233 | <td> | |
2234 | Location: | |
2235 | ||
2236 | <dl> | |
2237 | <dt>Entry | |
2238 | <dd><code><em>NAME</em>_entry</code> | |
2239 | ||
2240 | <dt>Exit | |
2241 | <dd><code><em>NAME</em>_exit</code> | |
2242 | </dl> | |
2243 | ||
2244 | where <code><em>NAME</em></code> is the lttng_event::name member | |
2245 | of the descriptor you used to create | |
2246 | \lt_var{ER} with lttng_enable_event_with_exclusions(). | |
2247 | </table> | |
2248 | ||
2249 | @defgroup api_pais Process attribute inclusion set API | |
2250 | @ingroup api_session | |
2251 | ||
2252 | To be done. | |
2253 | ||
2254 | @defgroup api_session_clear Recording session clearing API | |
2255 | @ingroup api_session | |
2256 | ||
2257 | This API makes it possible to clear a \lt_obj_session, that is, to | |
2258 | delete the contents of its tracing buffers and/or of all its | |
2259 | \ref api-session-local-mode "local" and | |
2260 | \ref api-session-net-mode "streamed" trace data. | |
2261 | ||
2262 | To clear a recording session: | |
2263 | ||
2264 | -# Call lttng_clear_session(), passing the name of the recording session | |
2265 | to clear. | |
2266 | ||
2267 | This function initiates a clearing operation, returning immediately. | |
2268 | ||
2269 | This function can set a pointer to a | |
2270 | \link #lttng_clear_handle clearing handle\endlink | |
2271 | so that you can wait for the completion of the | |
2272 | operation. Without such a handle, you can't know when the clearing | |
2273 | operation completes and whether or not it does successfully. | |
2274 | ||
2275 | -# <strong>If you have a clearing handle from step 1</strong>: | |
2276 | ||
2277 | -# Call lttng_clear_handle_wait_for_completion() to wait for the | |
2278 | completion of the clearing operation. | |
2279 | ||
2280 | -# Call lttng_clear_handle_get_result() to get whether or not the | |
2281 | clearing operation successfully completed. | |
2282 | ||
2283 | -# Destroy the clearing handle with lttng_clear_handle_destroy(). | |
2284 | ||
2285 | @sa \lt_man{lttng-clear,1} | |
2286 | ||
2287 | @defgroup api_session_snapshot Recording session snapshot API | |
2288 | @ingroup api_session | |
2289 | ||
2290 | To be done. | |
2291 | ||
2292 | @defgroup api_session_rotation Recording session rotation API | |
2293 | @ingroup api_session | |
2294 | ||
2295 | To be done. | |
2296 | ||
2297 | @defgroup api_session_save_load Recording session saving and loading API | |
2298 | @ingroup api_session | |
2299 | ||
2300 | To be done. | |
2301 | ||
2302 | @defgroup api_inst_pt Instrumentation point listing API | |
2303 | ||
2304 | The lttng_list_tracepoints() and lttng_list_syscalls() functions set a | |
2305 | pointer to an array of | |
2306 | <strong><em>\ref api-rer-inst-pt-descr "instrumentation point descriptors"</em></strong>. | |
2307 | ||
2308 | With those two functions, you can get details about the available | |
2309 | LTTng tracepoints, Java/Python loggers, and Linux kernel system calls, | |
2310 | as long as you can | |
2311 | \ref api-gen-sessiond-conn "connect to a session daemon". | |
2312 | You can then use the discovered information to create corresponding | |
2313 | \lt_obj_rers so that you can record the events | |
2314 | which LTTng creates from instrumentation points. | |
2315 | ||
2316 | See \ref api_rer to learn more about instrumentation points, events, | |
2317 | event records, and recording event rules. | |
2318 | ||
2319 | @defgroup api_trigger Trigger API | |
2320 | ||
2321 | To be done. | |
2322 | ||
2323 | @defgroup api_trigger_cond Trigger condition API | |
2324 | @ingroup api_trigger | |
2325 | ||
2326 | To be done. | |
2327 | ||
2328 | @defgroup api_trigger_cond_er_matches "Event rule matches" trigger condition API | |
2329 | @ingroup api_trigger_cond | |
2330 | ||
2331 | To be done. | |
2332 | ||
2333 | @defgroup api_er Event rule API | |
2334 | @ingroup api_trigger_cond_er_matches | |
2335 | ||
2336 | To be done. | |
2337 | ||
2338 | @defgroup api_ll_rule Log level rule API | |
2339 | @ingroup api_er | |
2340 | ||
2341 | To be done. | |
2342 | ||
2343 | @defgroup api_ev_expr Event expression API | |
2344 | @ingroup api_trigger_cond_er_matches | |
2345 | ||
2346 | To be done. | |
2347 | ||
2348 | @defgroup api_ev_field_val Event field value API | |
2349 | @ingroup api_trigger_cond_er_matches | |
2350 | ||
2351 | To be done. | |
2352 | ||
2353 | @defgroup api_trigger_action Trigger action API | |
2354 | @ingroup api_trigger | |
2355 | ||
2356 | To be done. | |
2357 | ||
2358 | @defgroup api_notif Notification API | |
2359 | @ingroup api_trigger_action | |
2360 | ||
2361 | To be done. | |
2362 | ||
2363 | @defgroup api_error Error query API | |
2364 | ||
2365 | To be done. | |
2366 | */ |