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> | |
777 | <td><a href="https://logging.apache.org/log4j/1.2/">Apache log4j</a> | |
778 | <td>#LTTNG_DOMAIN_LOG4J | |
779 | <tr> | |
780 | <td><a href="https://docs.python.org/3/library/logging.html">Python logging</a> | |
781 | <td>#LTTNG_DOMAIN_PYTHON | |
782 | </table> | |
783 | ||
784 | A \lt_obj_channel is always part of a tracing domain. | |
785 | ||
786 | Many liblttng-ctl functions require a tracing domain type (sometimes | |
787 | within a | |
788 | \link #lttng_handle recording session handle\endlink) | |
789 | to target specific tracers or to avoid ambiguity. For example, because | |
790 | the Linux kernel and user space tracing domains support named | |
791 | tracepoints as \ref api_inst_pt "instrumentation points", you need to | |
792 | specify a tracing domain when you create a | |
793 | \lt_obj_rer with lttng_enable_event_with_exclusions() because both | |
794 | tracing domains could have LTTng tracepoints sharing the same name. | |
795 | ||
796 | @sa The <em>TRACING DOMAIN</em> section of \lt_man{lttng-concepts,7}. | |
797 | ||
798 | <h1>\anchor api-channel-channel Channel</h1> | |
799 | ||
800 | A <strong><em>channel</em></strong> is an object which is responsible | |
801 | for a set of ring buffers. | |
802 | ||
803 | Each ring buffer is divided into multiple <em>sub-buffers</em>. When a | |
804 | \lt_obj_rer matches an event, LTTng can record it to one or more | |
805 | sub-buffers of one or more channels. | |
806 | ||
807 | A channel is always associated to a \lt_obj_domain. | |
808 | The \link #LTTNG_DOMAIN_JUL <code>java.util.logging</code>\endlink, | |
809 | \link #LTTNG_DOMAIN_LOG4J Apache log4j\endlink, and | |
810 | \link #LTTNG_DOMAIN_PYTHON Python\endlink tracing | |
811 | domains each have a default channel which you can't configure. | |
812 | ||
813 | Note that the some functions, like lttng_enable_event_with_exclusions(), | |
814 | can automatically create a default channel with sane defaults when no | |
815 | channel exists for the provided \lt_obj_domain. | |
816 | ||
817 | A channel owns \lt_obj_rers. | |
818 | ||
819 | @image html concepts.png "A recording session contains channels that are members of tracing domains and contain recording event rules." | |
820 | ||
821 | You can't destroy a channel. | |
822 | ||
823 | <h2>Operations</h2> | |
824 | ||
825 | The channel operations are: | |
826 | ||
827 | <table> | |
828 | <tr> | |
829 | <th>Operation | |
830 | <th>Means | |
831 | <tr> | |
832 | <td>Creation | |
833 | <td> | |
834 | -# Call lttng_channel_create() with a \lt_obj_domain summary to | |
835 | create an initial channel summary. | |
836 | ||
837 | This function calls lttng_channel_set_default_attr() to set | |
838 | the properties of the created channel summary to default values | |
839 | depending on the tracing domain summary. | |
840 | ||
841 | -# Set the properties of the channel summary of step 1 | |
842 | through direct members or with dedicated setters. | |
843 | ||
844 | See the property table below. | |
845 | ||
846 | -# Create a \link #lttng_handle recording session handle\endlink | |
847 | structure to specify the name of the recording session and the | |
848 | tracing domain of the channel to create. | |
849 | ||
850 | -# Call lttng_enable_channel() with the recording session handle | |
851 | of step 3 and the channel summary of step 1 | |
852 | o create the channel. | |
853 | ||
854 | -# Destroy the recording session handle with | |
855 | lttng_destroy_handle() and the channel summary with | |
856 | lttng_channel_destroy(). | |
857 | ||
858 | @sa \lt_man{lttng-enable-channel,1} | |
859 | <tr> | |
860 | <td>Basic property access | |
861 | <td> | |
862 | See the \ref api-channel-channel-props "property table" below. | |
863 | <tr> | |
864 | <td>\lt_obj_c_rer access | |
865 | <td> | |
866 | -# Create a \link #lttng_handle recording session handle\endlink | |
867 | with lttng_create_handle() to specify the name of the | |
868 | recording session and the summary of the | |
869 | \lt_obj_domain of the channel of which to get the recording | |
870 | event rule descriptors. | |
871 | ||
872 | -# Call lttng_list_events(), passing the recording session | |
873 | handle of step 1 and a channel name. | |
874 | ||
875 | This function sets a pointer to an array of | |
876 | \link #lttng_event recording event rule descriptors\endlink | |
877 | and returns the number of entries. | |
878 | ||
879 | -# Destroy the recording session handle of step 1 with | |
880 | lttng_destroy_handle(). | |
881 | ||
882 | -# Access the properties of each | |
883 | recording event rule descriptor through structure members or | |
884 | using dedicated getters. | |
885 | ||
886 | -# When you're done with the array of recording event rule | |
887 | descriptors, free it with <code>free()</code>. | |
888 | <tr> | |
889 | <td>Event record context field adding | |
890 | <td> | |
891 | -# Initialize a #lttng_event_context structure, setting | |
892 | its properties to describe the context field to be added. | |
893 | ||
894 | -# Create a \link #lttng_handle recording session handle\endlink | |
895 | structure to specify the name of the recording session and the | |
896 | tracing domain of the channel to create. | |
897 | ||
898 | -# Call lttng_add_context() with the recording session handle | |
899 | of step 2 and the context field descriptor of step 1, | |
900 | optionally passing the name of the channel to target. | |
901 | ||
902 | -# Destroy the recording session handle with | |
903 | lttng_destroy_handle(). | |
904 | ||
905 | @sa \lt_man{lttng-add-context,1} | |
906 | <tr> | |
907 | <td>Enabling | |
908 | <td> | |
909 | Use lttng_enable_channel(). | |
910 | ||
911 | @sa \lt_man{lttng-enable-channel,1} | |
912 | <tr> | |
913 | <td>Disabling | |
914 | <td> | |
915 | Use lttng_disable_channel(). | |
916 | ||
917 | @sa \lt_man{lttng-disable-channel,1} | |
918 | <tr> | |
919 | <td>Statistics | |
920 | <td> | |
921 | See: | |
922 | ||
923 | - lttng_channel_get_discarded_event_count() | |
924 | - lttng_channel_get_lost_packet_count() | |
925 | </table> | |
926 | ||
927 | <h2>\anchor api-channel-channel-props Properties</h2> | |
928 | ||
929 | The properties of a channel are: | |
930 | ||
931 | <table> | |
932 | <tr> | |
933 | <th>Property name | |
934 | <th>Description | |
935 | <th>Access | |
936 | <tr> | |
937 | <td>Buffering scheme | |
938 | <td> | |
939 | See \ref api-channel-buf-scheme "Buffering scheme". | |
940 | <td> | |
941 | The lttng_domain::buf_type member for the containing tracing | |
942 | domain. | |
943 | ||
944 | All the channels of a given tracing domain share the same | |
945 | buffering scheme. | |
946 | <tr> | |
947 | <td>Event record loss mode | |
948 | <td> | |
949 | See \ref api-channel-er-loss-mode "Event record loss mode". | |
950 | <td> | |
951 | The lttng_channel_attr::overwrite member. | |
952 | <tr> | |
953 | <td>Sub-buffer size | |
954 | <td> | |
955 | See \ref api-channel-sub-buf-size-count "Sub-buffer size and count". | |
956 | <td> | |
957 | The lttng_channel_attr::subbuf_size member. | |
958 | <tr> | |
959 | <td>Sub-buffer count | |
960 | <td> | |
961 | See \ref api-channel-sub-buf-size-count "Sub-buffer size and count". | |
962 | <td> | |
963 | The lttng_channel_attr::num_subbuf member. | |
964 | <tr> | |
965 | <td>Maximum trace file size | |
966 | <td> | |
967 | See \ref api-channel-max-trace-file-size-count "Maximum trace file size and count". | |
968 | <td> | |
969 | The lttng_channel_attr::tracefile_size member. | |
970 | <tr> | |
971 | <td>Maximum trace file count | |
972 | <td> | |
973 | See \ref api-channel-max-trace-file-size-count "Maximum trace file size and count". | |
974 | <td> | |
975 | The lttng_channel_attr::tracefile_count member. | |
976 | <tr> | |
977 | <td>Read timer period | |
978 | <td> | |
979 | See \ref api-channel-read-timer "Read timer". | |
980 | <td> | |
981 | The lttng_channel_attr::read_timer_interval member. | |
982 | <tr> | |
983 | <td>Switch timer period | |
984 | <td> | |
985 | See \ref api-channel-switch-timer "Switch timer". | |
986 | <td> | |
987 | The lttng_channel_attr::switch_timer_interval member. | |
988 | <tr> | |
989 | <td>Live timer period | |
990 | <td> | |
991 | See \ref api-channel-live-timer "Live timer". | |
992 | <td> | |
993 | The \lt_p{live_timer_period} parameter of | |
994 | lttng_session_descriptor_live_network_create() when you create | |
995 | the descriptor of a \ref api-session-live-mode "live" recording | |
996 | session to contain the channel. | |
997 | <tr> | |
998 | <td>Monitor timer period | |
999 | <td> | |
1000 | See \ref api-channel-monitor-timer "Monitor timer". | |
1001 | <td> | |
1002 | - lttng_channel_get_monitor_timer_interval() | |
1003 | - lttng_channel_set_monitor_timer_interval() | |
1004 | <tr> | |
1005 | <td>Output type (Linux kernel channel) | |
1006 | <td> | |
1007 | Whether to use <code>mmap()</code> or <code>splice()</code>. | |
1008 | <td> | |
1009 | The lttng_channel_attr::output member. | |
1010 | <tr> | |
1011 | <td>\anchor api-channel-blocking-timeout Blocking timeout (user space channel) | |
1012 | <td> | |
1013 | How long to block (if ever) at the instrumentation point site when | |
1014 | a sub-buffer is not available for applications executed with the | |
1015 | \c LTTNG_UST_ALLOW_BLOCKING environment variable set. | |
1016 | <td> | |
1017 | - lttng_channel_get_blocking_timeout() | |
1018 | - lttng_channel_set_blocking_timeout() | |
1019 | </table> | |
1020 | ||
1021 | All the properties above are immutable once a channel exists. | |
1022 | ||
1023 | @sa The <em>CHANNEL AND RING BUFFER</em> section of | |
1024 | \lt_man{lttng-concepts,7}. | |
1025 | ||
1026 | <h3>\anchor api-channel-buf-scheme Buffering scheme</h3> | |
1027 | ||
1028 | A channel has at least one ring buffer per CPU. LTTng always records an | |
1029 | event to the ring buffer dedicated to the CPU which emits it. | |
1030 | ||
1031 | The <strong><em>buffering scheme</em></strong> of a | |
1032 | \link #LTTNG_DOMAIN_UST user space\endlink | |
1033 | channel determines what has its own set of per-CPU | |
1034 | ring buffers, considering \lt_var{U} is the Unix user of the process | |
1035 | running liblttng-ctl: | |
1036 | ||
1037 | <dl> | |
1038 | <dt> | |
1039 | \anchor api-channel-per-user-buf | |
1040 | \link #LTTNG_BUFFER_PER_UID Per-user buffering\endlink | |
1041 | <dd> | |
1042 | Allocate one set of ring buffers (one per CPU) shared by all the | |
1043 | instrumented processes of: | |
1044 | ||
1045 | <dl> | |
1046 | <dt>If \lt_var{U} is <code>root</code> | |
1047 | <dd> | |
1048 | Each Unix user. | |
1049 | ||
1050 | @image html per-user-buffering-root.png | |
1051 | ||
1052 | <dt>Otherwise | |
1053 | <dd> | |
1054 | \lt_var{U} | |
1055 | ||
1056 | @image html per-user-buffering.png | |
1057 | </dl> | |
1058 | ||
1059 | <dt> | |
1060 | \anchor api-channel-per-proc-buf | |
1061 | \link #LTTNG_BUFFER_PER_PID Per-process buffering\endlink | |
1062 | <dd> | |
1063 | Allocate one set of ring buffers (one per CPU) for each | |
1064 | instrumented process of: | |
1065 | ||
1066 | <dl> | |
1067 | <dt>If \lt_var{U} is <code>root</code> | |
1068 | <dd> | |
1069 | All Unix users. | |
1070 | ||
1071 | @image html per-process-buffering-root.png | |
1072 | ||
1073 | <dt>Otherwise | |
1074 | <dd> | |
1075 | \lt_var{U} | |
1076 | ||
1077 | @image html per-process-buffering.png | |
1078 | </dl> | |
1079 | </dl> | |
1080 | ||
1081 | The per-process buffering scheme tends to consume more memory than the | |
1082 | per-user option because systems generally have more instrumented | |
1083 | processes than Unix users running instrumented processes. However, the | |
1084 | per-process buffering scheme ensures that one process having a high | |
1085 | event throughput won't fill all the shared sub-buffers of the same Unix | |
1086 | user, only its own. | |
1087 | ||
1088 | The buffering scheme of a Linux kernel (#LTTNG_DOMAIN_KERNEL) channel is | |
1089 | always to allocate a single set of ring buffers for the whole system | |
1090 | (#LTTNG_BUFFER_GLOBAL). This scheme is similar to the | |
1091 | \ref api-channel-per-user-buf "per-user" one, but with a single, global | |
1092 | user "running" the kernel. | |
1093 | ||
1094 | To set the buffering scheme of a channel when you create it: | |
1095 | ||
1096 | - Set the lttng_domain::buf_type member of the structure which you pass | |
1097 | within the #lttng_handle structure to lttng_enable_channel(). | |
1098 | ||
1099 | Note that, for a given \lt_obj_session, \em all | |
1100 | the channels of a given \lt_obj_domain must share the same buffering | |
1101 | scheme. | |
1102 | ||
1103 | @sa The <em>Buffering scheme</em> section of \lt_man{lttng-concepts,7}. | |
1104 | ||
1105 | <h3>\anchor api-channel-er-loss-mode Event record loss mode</h3> | |
1106 | ||
1107 | When LTTng emits an event, LTTng can record it to a specific, available | |
1108 | sub-buffer within the ring buffers of specific channels. When there's no | |
1109 | space left in a sub-buffer, the tracer marks it as consumable and | |
1110 | another, available sub-buffer starts receiving the following event | |
1111 | records. An LTTng consumer daemon eventually consumes the marked | |
1112 | sub-buffer, which returns to the available state. | |
1113 | ||
1114 | In an ideal world, sub-buffers are consumed faster than they are filled. | |
1115 | In the real world, however, all sub-buffers can be full at some point, | |
1116 | leaving no space to record the following events. | |
1117 | ||
1118 | By default, LTTng-modules and LTTng-UST are <em>non-blocking</em> | |
1119 | tracers: when there's no available sub-buffer to record an event, it's | |
1120 | acceptable to lose event records when the alternative would be to cause | |
1121 | substantial delays in the execution of the instrumented application. | |
1122 | LTTng privileges performance over integrity; it aims at perturbing the | |
1123 | instrumented application as little as possible in order to make the | |
1124 | detection of subtle race conditions and rare interrupt cascades | |
1125 | possible. | |
1126 | ||
1127 | Since LTTng 2.10, the LTTng user space tracer, LTTng-UST, supports | |
1128 | a <em>blocking mode</em>: see lttng_channel_get_blocking_timeout() and | |
1129 | lttng_channel_set_blocking_timeout(). | |
1130 | ||
1131 | When it comes to losing event records because there's no available | |
1132 | sub-buffer, or because the blocking timeout of the channel is reached, | |
1133 | the <strong><em>event record loss mode</em></strong> of the channel | |
1134 | determines what to do. The available event record loss modes are: | |
1135 | ||
1136 | <dl> | |
1137 | <dt>\anchor api-channel-discard-mode Discard mode | |
1138 | <dd> | |
1139 | Drop the newest event records until a sub-buffer becomes available. | |
1140 | ||
1141 | This is the only available mode when you specify a blocking timeout | |
1142 | with lttng_channel_set_blocking_timeout(). | |
1143 | ||
1144 | With this mode, LTTng increments a count of discarded event records | |
1145 | when it discards an event record and saves this count to the trace. | |
1146 | A trace reader can use the saved discarded event record count of the | |
1147 | trace to decide whether or not to perform some analysis even if | |
1148 | trace data is known to be missing. | |
1149 | ||
1150 | Get the number of discarded event records of a channel with | |
1151 | lttng_channel_get_discarded_event_count(). | |
1152 | ||
1153 | <dt>\anchor api-channel-overwrite-mode Overwrite mode | |
1154 | <dd> | |
1155 | Clear the sub-buffer containing the oldest event records and start | |
1156 | writing the newest event records there. | |
1157 | ||
1158 | This mode is sometimes called <em>flight recorder mode</em> because | |
1159 | it's similar to a | |
1160 | <a href="https://en.wikipedia.org/wiki/Flight_recorder">flight recorder</a>: | |
1161 | always keep a fixed amount of the latest data. It's also | |
1162 | similar to the roll mode of an oscilloscope. | |
1163 | ||
1164 | Since LTTng 2.8, with this mode, LTTng writes to a given | |
1165 | sub-buffer its sequence number within its data stream. With a | |
1166 | \ref api-session-local-mode "local", | |
1167 | \ref api-session-net-mode "network streaming", or | |
1168 | \ref api-session-live-mode "live" recording session, a trace | |
1169 | reader can use such sequence numbers to report discarded packets. A | |
1170 | trace reader can use the saved discarded sub-buffer (packet) count | |
1171 | of the trace to decide whether or not to perform some analysis even | |
1172 | if trace data is known to be missing. | |
1173 | ||
1174 | Get the number of discarded packets (sub-buffers) of a channel with | |
1175 | lttng_channel_get_lost_packet_count(). | |
1176 | ||
1177 | With this mode, LTTng doesn't write to the trace the exact number of | |
1178 | lost event records in the lost sub-buffers. | |
1179 | </dl> | |
1180 | ||
1181 | Which mechanism you should choose depends on your context: prioritize | |
1182 | the newest or the oldest event records in the ring buffer? | |
1183 | ||
1184 | Beware that, in overwrite mode, the tracer abandons a <em>whole | |
1185 | sub-buffer</em> as soon as a there's no space left for a new event | |
1186 | record, whereas in discard mode, the tracer only discards the event | |
1187 | record that doesn't fit. | |
1188 | ||
1189 | To set the event record loss mode of a channel when you create it: | |
1190 | ||
1191 | - Set the lttng_channel_attr::overwrite member of the lttng_channel::attr | |
1192 | member of the structure you pass to lttng_enable_channel(). | |
1193 | ||
1194 | There are a few ways to decrease your probability of losing event | |
1195 | records. The | |
1196 | \ref api-channel-sub-buf-size-count "Sub-buffer size and count" section | |
1197 | shows how to fine-tune the sub-buffer size and count of a channel to | |
1198 | virtually stop losing event records, though at the cost of greater | |
1199 | memory usage. | |
1200 | ||
1201 | @sa The <em>Event record loss mode</em> section of | |
1202 | \lt_man{lttng-concepts,7}. | |
1203 | ||
1204 | <h3>\anchor api-channel-sub-buf-size-count Sub-buffer size and count</h3> | |
1205 | ||
1206 | A channel has one or more ring buffer for each CPU of the target system. | |
1207 | ||
1208 | See \ref api-channel-buf-scheme "Buffering scheme" to learn how many | |
1209 | ring buffers of a given channel are dedicated to each CPU depending on | |
1210 | its buffering scheme. | |
1211 | ||
1212 | To set the size of each sub-buffer the ring buffers of a channel have | |
1213 | when you create it: | |
1214 | ||
1215 | - Set the lttng_channel_attr::subbuf_size member of the | |
1216 | lttng_channel::attr member of the structure you pass to | |
1217 | lttng_enable_channel(). | |
1218 | ||
1219 | To set the number of sub-buffers each ring buffer of a channel has | |
1220 | when you create it: | |
1221 | ||
1222 | - Set the lttng_channel_attr::num_subbuf member of the | |
1223 | lttng_channel::attr member of the structure you pass to | |
1224 | lttng_enable_channel(). | |
1225 | ||
1226 | Note that LTTng switching the current sub-buffer of a ring buffer | |
1227 | (marking a full one as consumable and switching to an available one for | |
1228 | LTTng to record the next events) introduces noticeable CPU overhead. | |
1229 | Knowing this, the following list presents a few practical situations | |
1230 | along with how to configure the sub-buffer size and count for them: | |
1231 | ||
1232 | <dl> | |
1233 | <dt>High event throughput | |
1234 | <dd> | |
1235 | In general, prefer large sub-buffers to lower the risk of losing | |
1236 | event records. | |
1237 | ||
1238 | Having larger sub-buffers also ensures a lower sub-buffer | |
1239 | \ref api-channel-switch-timer "switching frequency". | |
1240 | ||
1241 | The sub-buffer count is only meaningful if you create the channel in | |
1242 | \ref api-channel-overwrite-mode "overwrite mode": in this case, if | |
1243 | LTTng overwrites a sub-buffer, then the other sub-buffers are left | |
1244 | unaltered. | |
1245 | ||
1246 | <dt>Low event throughput | |
1247 | <dd> | |
1248 | In general, prefer smaller sub-buffers since the risk of losing | |
1249 | event records is low. | |
1250 | ||
1251 | Because LTTng emits events less frequently, the sub-buffer switching | |
1252 | frequency should remain low and therefore the overhead of the tracer | |
1253 | shouldn't be a problem. | |
1254 | ||
1255 | <dt>Low memory system | |
1256 | <dd> | |
1257 | If your target system has a low memory limit, prefer fewer first, | |
1258 | then smaller sub-buffers. | |
1259 | ||
1260 | Even if the system is limited in memory, you want to keep the | |
1261 | sub-buffers as large as possible to avoid a high sub-buffer | |
1262 | switching frequency. | |
1263 | </dl> | |
1264 | ||
1265 | Note that LTTng uses <a href="https://diamon.org/ctf/">CTF</a> as its | |
1266 | trace format, which means event record data is very compact. For | |
1267 | example, the average LTTng kernel event record weights about | |
1268 | 32 bytes. Therefore, a sub-buffer size of 1 MiB is considered | |
1269 | large. | |
1270 | ||
1271 | The previous scenarios highlight the major trade-off between a few large | |
1272 | sub-buffers and more, smaller sub-buffers: sub-buffer switching | |
1273 | frequency vs. how many event records are lost in | |
1274 | \ref api-channel-overwrite-mode "overwrite mode". | |
1275 | Assuming a constant event throughput and using the overwrite mode, the | |
1276 | two following configurations have the same ring buffer total size: | |
1277 | ||
1278 | <dl> | |
1279 | <dt>Two sub-buffers of 4 MiB each | |
1280 | <dd> | |
1281 | Expect a very low sub-buffer switching frequency, but if LTTng ever | |
1282 | needs to overwrite a sub-buffer, half of the event records so far | |
1283 | (4 MiB) are definitely lost. | |
1284 | ||
1285 | <dt>Eight sub-buffers of 1 MiB each | |
1286 | <dd> | |
1287 | Expect four times the tracer overhead of the configuration above, | |
1288 | but if LTTng needs to overwrite a sub-buffer, only the eighth of | |
1289 | event records so far (1 MiB) are definitely lost. | |
1290 | </dl> | |
1291 | ||
1292 | In \ref api-channel-discard-mode "discard mode", the sub-buffer count | |
1293 | parameter is pointless: use two sub-buffers and set their size according | |
1294 | to your requirements. | |
1295 | ||
1296 | @sa The <em>Sub-buffer size and count</em> section of | |
1297 | \lt_man{lttng-concepts,7}. | |
1298 | ||
1299 | <h3>\anchor api-channel-max-trace-file-size-count Maximum trace file size and count</h3> | |
1300 | ||
1301 | By default, trace files can grow as large as needed. | |
1302 | ||
1303 | To set the maximum size of each trace file that LTTng writes from the | |
1304 | ring buffers of a channel when you create it: | |
1305 | ||
1306 | - Set the lttng_channel_attr::tracefile_size member of the | |
1307 | lttng_channel::attr member of the structure you pass to | |
1308 | lttng_enable_channel(). | |
1309 | ||
1310 | When the size of a trace file reaches the fixed maximum size of the | |
1311 | channel, LTTng creates another file to contain the next event records. | |
1312 | LTTng appends a file count to each trace file name in this case. | |
1313 | ||
1314 | If you set the trace file size attribute when you create a channel, the | |
1315 | maximum number of trace files that LTTng creates is <em>unlimited</em> | |
1316 | by default. | |
1317 | ||
1318 | To limit the size of each trace file that LTTng writes from the | |
1319 | ring buffers of a channel when you create it: | |
1320 | ||
1321 | - Set the lttng_channel_attr::tracefile_count member of the | |
1322 | lttng_channel::attr member of the structure you pass to | |
1323 | lttng_enable_channel(). | |
1324 | ||
1325 | When the number of trace files reaches the fixed maximum count of the | |
1326 | channel, LTTng overwrites the oldest trace file. This mechanism is | |
1327 | called <em>trace file rotation</em>. | |
1328 | ||
1329 | @attention | |
1330 | @parblock | |
1331 | Even if you don't limit the trace file count, always assume that | |
1332 | LTTng manages all the trace files of the recording session. | |
1333 | ||
1334 | In other words, there's no safe way to know if LTTng still holds a | |
1335 | given trace file open with the trace file rotation feature. | |
1336 | ||
1337 | The only way to obtain an unmanaged, self-contained LTTng trace | |
1338 | before you \link lttng_destroy_session_ext() destroy the | |
1339 | recording session\endlink is with the | |
1340 | \ref api_session_rotation "recording session rotation" feature, | |
1341 | which is available since LTTng 2.11. | |
1342 | @endparblock | |
1343 | ||
1344 | @sa The <em>Maximum trace file size and count</em> section of | |
1345 | \lt_man{lttng-concepts,7}. | |
1346 | ||
1347 | <h3>\anchor api-channel-timers Timers</h3> | |
1348 | ||
1349 | Each channel can have up to four optional | |
1350 | <strong><em>timers</em></strong>: | |
1351 | ||
1352 | <dl> | |
1353 | <dt>\anchor api-channel-switch-timer Switch timer | |
1354 | <dd> | |
1355 | When this timer expires, a sub-buffer switch happens: for each ring | |
1356 | buffer of the channel, LTTng marks the current sub-buffer as | |
1357 | consumable and switches to an available one to record the next | |
1358 | events. | |
1359 | ||
1360 | A switch timer is useful to ensure that LTTng consumes and commits | |
1361 | trace data to trace files or to a distant relay daemon | |
1362 | (see \lt_man{lttng-relayd,8}) periodically in case of a low event | |
1363 | throughput. | |
1364 | ||
1365 | Such a timer is also convenient when you use | |
1366 | \ref api-channel-sub-buf-size-count "large sub-buffers" | |
1367 | to cope with a sporadic high event throughput, even if the | |
1368 | throughput is otherwise low. | |
1369 | ||
1370 | To set the period of the switch timer of a channel when you create | |
1371 | it: | |
1372 | ||
1373 | - Set the lttng_channel_attr::switch_timer_interval member of the | |
1374 | lttng_channel::attr member of the structure you pass to | |
1375 | lttng_enable_channel(). | |
1376 | ||
1377 | A channel only has a switch timer when its | |
1378 | recording session is \em not in | |
1379 | \ref api-session-live-mode "live mode". lttng_enable_channel() | |
1380 | ignores the lttng_channel_attr::switch_timer_interval member with a | |
1381 | live recording session. For a live recording session, the | |
1382 | \ref api-channel-live-timer "live timer" plays the role of the | |
1383 | switch timer. | |
1384 | ||
1385 | <dt>\anchor api-channel-live-timer Live timer | |
1386 | <dd> | |
1387 | Like the \ref api-channel-switch-timer "switch timer", but for a | |
1388 | channel which belongs to a | |
1389 | \ref api-session-live-mode "live" recording session. | |
1390 | ||
1391 | If this timer expires but there's no sub-buffer to consume, LTTng | |
1392 | sends a message with a timestamp to the connected relay daemon (see | |
1393 | \lt_man{lttng-relayd,8}) so that its live readers can progress. | |
1394 | ||
1395 | To set the period of the live timer of a channel when you create | |
1396 | its recording session: | |
1397 | ||
1398 | - Set the \lt_p{live_timer_period} parameter when you call | |
1399 | lttng_session_descriptor_live_network_create() to create a | |
1400 | live recording session descriptor to pass to | |
1401 | lttng_create_session_ext(). | |
1402 | ||
1403 | @note | |
1404 | All the channels of a live recording session share the same | |
1405 | live timer period. | |
1406 | ||
1407 | <dt>\anchor api-channel-read-timer Read timer | |
1408 | <dd> | |
1409 | When this timer expires, LTTng checks for full, consumable | |
1410 | sub-buffers. | |
1411 | ||
1412 | By default, the LTTng tracers use an asynchronous message mechanism | |
1413 | to signal a full sub-buffer so that a consumer daemon can consume | |
1414 | it. | |
1415 | ||
1416 | When such messages must be avoided, for example in real-time | |
1417 | applications, use this timer instead. | |
1418 | ||
1419 | To set the period of the read timer of a channel when you create | |
1420 | it: | |
1421 | ||
1422 | - Set the lttng_channel_attr::read_timer_interval member of the | |
1423 | lttng_channel::attr member of the structure you pass to | |
1424 | lttng_enable_channel(). | |
1425 | ||
1426 | <dt>\anchor api-channel-monitor-timer Monitor timer | |
1427 | <dd> | |
1428 | When this timer expires, the consumer daemon samples some channel | |
1429 | statistics to evaluate the following trigger conditions: | |
1430 | ||
1431 | -# The consumed buffer size of a given recording session becomes | |
1432 | greater than some value. | |
1433 | ||
1434 | -# The buffer usage of a given channel becomes greater than some | |
1435 | value. | |
1436 | ||
1437 | -# The buffer usage of a given channel becomes less than some value. | |
1438 | ||
1439 | If you disable the monitor timer of a channel \lt_var{C}: | |
1440 | ||
1441 | - The consumed buffer size value of the recording session | |
1442 | of \lt_var{C} could be wrong for trigger condition | |
1443 | type 1: the consumed buffer size of \lt_var{C} won't be | |
1444 | part of the grand total. | |
1445 | ||
1446 | - The buffer usage trigger conditions (types 2 and 3) | |
1447 | for \lt_var{C} will never be satisfied. | |
1448 | ||
1449 | See \ref api_trigger to learn more about triggers. | |
1450 | ||
1451 | To set the period of the monitor timer of a channel when you create | |
1452 | it: | |
1453 | ||
1454 | - Call lttng_channel_set_monitor_timer_interval() with the | |
1455 | #lttng_channel structure you pass to lttng_enable_channel(). | |
1456 | </dl> | |
1457 | ||
1458 | @sa The <em>Timers</em> section of \lt_man{lttng-concepts,7}. | |
1459 | ||
1460 | @defgroup api_rer Recording event rule API | |
1461 | @ingroup api_channel | |
1462 | ||
1463 | <h1>Concepts</h1> | |
1464 | ||
1465 | An <em>instrumentation point</em> is a point, within a piece of | |
1466 | software, which, when executed, creates an LTTng <em>event</em>. | |
1467 | See \ref api_inst_pt to learn how to list the available instrumentation | |
1468 | points. | |
1469 | ||
1470 | An <em>event rule</em> is a set of \ref api-rer-conds "conditions" to | |
1471 | match a set of events. | |
1472 | ||
1473 | A <strong><em>recording event rule</em></strong> is a specific type of | |
1474 | event rule of which the action is to serialize and write the matched | |
1475 | event as an <em>event record</em> to a sub-buffer of its attached | |
1476 | \lt_obj_channel. | |
1477 | ||
1478 | An event record has a \ref api-rer-er-name "name" and fields. | |
1479 | ||
1480 | When LTTng creates an event \lt_var{E}, a recording event | |
1481 | rule \lt_var{ER} is said to <em>match</em> \lt_var{E} | |
1482 | when \lt_var{E} satisfies \em all the conditions | |
1483 | of \lt_var{ER}. This concept is similar to a regular expression | |
1484 | which matches a set of strings. | |
1485 | ||
1486 | When a recording event rule matches an event, LTTng \em emits the event, | |
1487 | therefore attempting to record it. | |
1488 | ||
1489 | @attention | |
1490 | @parblock | |
1491 | The event creation and emission processes are \em documentation | |
1492 | concepts to help understand the journey from an instrumentation | |
1493 | point to an event record. | |
1494 | ||
1495 | The actual creation of an event can be costly because LTTng needs to | |
1496 | evaluate the arguments of the instrumentation point. | |
1497 | ||
1498 | In practice, LTTng implements various optimizations for the | |
1499 | \link #LTTNG_DOMAIN_KERNEL Linux kernel\endlink and | |
1500 | \link #LTTNG_DOMAIN_UST user space\endlink \lt_obj_domains | |
1501 | to avoid actually creating an event when the tracer knows, thanks to | |
1502 | properties which are independent from the event payload and current | |
1503 | \link #lttng_event_context_type context\endlink, that it would never | |
1504 | emit such an event. Those properties are: | |
1505 | ||
1506 | - The \ref api-rer-conds-inst-pt-type "instrumentation point type". | |
1507 | ||
1508 | - The \ref api-rer-conds-event-name "instrumentation point name" (or | |
1509 | event name). | |
1510 | ||
1511 | - The \ref api-rer-conds-ll "instrumentation point log level". | |
1512 | ||
1513 | - The \link lttng_event::enabled status\endlink (enabled or | |
1514 | disabled) of the rule itself. | |
1515 | ||
1516 | - The \link lttng_channel::enabled status\endlink (enabled or | |
1517 | disabled) of the \lt_obj_channel containing the rule. | |
1518 | ||
1519 | - The \link lttng_session::enabled activity\endlink (started or | |
1520 | stopped) of the \lt_obj_session containing the rule. | |
1521 | ||
1522 | - Whether or not the process for which LTTng would create the event | |
1523 | is \ref api_pais "allowed to record events". | |
1524 | ||
1525 | In other words: if, for a given instrumentation point \lt_var{IP}, | |
1526 | the LTTng tracer knows that it would never emit an event, | |
1527 | executing \lt_var{IP} represents a simple boolean variable check | |
1528 | and, for a \link #LTTNG_DOMAIN_KERNEL Linux kernel\endlink | |
1529 | \lt_obj_rer, a few current process attribute checks. | |
1530 | @endparblock | |
1531 | ||
1532 | You always attach a recording event rule to a | |
1533 | \lt_obj_channel, which belongs to | |
1534 | a \lt_obj_session, when you | |
1535 | \link lttng_enable_event_with_exclusions() create it\endlink. | |
1536 | A channel owns recording event rules. | |
1537 | ||
1538 | When multiple matching recording event rules are attached to the same | |
1539 | channel, LTTng attempts to serialize and record the matched event | |
1540 | <em>once</em>. | |
1541 | ||
1542 | @image html event-rule.png "Logical path from an instrumentation point to an event record." | |
1543 | ||
1544 | As of LTTng-tools \lt_version_maj_min, you cannot remove a | |
1545 | recording event rule: it exists as long as its \lt_obj_session exists. | |
1546 | ||
1547 | <h1>Operations</h1> | |
1548 | ||
1549 | The recording event rule operations are: | |
1550 | ||
1551 | <table> | |
1552 | <tr> | |
1553 | <th>Operation | |
1554 | <th>Means | |
1555 | <tr> | |
1556 | <td>Creation | |
1557 | <td> | |
1558 | -# Call lttng_event_create() to create an initial | |
1559 | \link #lttng_event recording event rule descriptor\endlink. | |
1560 | ||
1561 | -# Set the properties of the recording event rule descriptor of | |
1562 | step 1 through direct members or with dedicated setters. | |
1563 | ||
1564 | See the property table below. | |
1565 | ||
1566 | -# Create a \link #lttng_handle recording session handle\endlink | |
1567 | structure to specify the name of the recording session and the | |
1568 | tracing domain of the recording event rule to create. | |
1569 | ||
1570 | -# Call lttng_enable_event_with_exclusions() with the recording | |
1571 | session handle of step 3, the recording event rule | |
1572 | descriptor of step 1, the name of a | |
1573 | \lt_obj_channel to which to attach the | |
1574 | created recording event rule, and, depending on the selected | |
1575 | function, other properties to create the rule. | |
1576 | ||
1577 | -# Destroy the recording session handle with | |
1578 | lttng_destroy_handle() and the recording event rule descriptor | |
1579 | with lttng_event_destroy(). | |
1580 | ||
1581 | @sa \lt_man{lttng-enable-event,1} | |
1582 | <tr> | |
1583 | <td>Property access | |
1584 | <td> | |
1585 | See: | |
1586 | ||
1587 | - The members of #lttng_event | |
1588 | - lttng_event_get_userspace_probe_location() | |
1589 | - lttng_event_set_userspace_probe_location() | |
1590 | - lttng_event_get_filter_expression() | |
1591 | - lttng_event_get_exclusion_name_count() | |
1592 | - lttng_event_get_exclusion_name() | |
1593 | ||
1594 | @sa \ref api-rer-conds "Recording event rule conditions". | |
1595 | <tr> | |
1596 | <td>Enabling | |
1597 | <td> | |
1598 | With an #lttng_event instance which comes from | |
1599 | lttng_list_events(), use lttng_enable_event(). | |
1600 | ||
1601 | Otherwise, use lttng_enable_event_with_exclusions(). | |
1602 | ||
1603 | @sa \lt_man{lttng-enable-event,1} | |
1604 | <tr> | |
1605 | <td>Disabling | |
1606 | <td> | |
1607 | Use lttng_disable_event() or lttng_disable_event_ext(). | |
1608 | ||
1609 | @sa \lt_man{lttng-disable-event,1} | |
1610 | </table> | |
1611 | ||
1612 | <h1>\anchor api-rer-conds Recording event rule conditions</h1> | |
1613 | ||
1614 | For LTTng to emit and record an event \lt_var{E}, \lt_var{E} | |
1615 | must satisfy \em all the conditions of a recording event | |
1616 | rule \lt_var{ER}, that is: | |
1617 | ||
1618 | <dl> | |
1619 | <dt>Explicit conditions | |
1620 | <dd> | |
1621 | You set the following conditions when you | |
1622 | \link lttng_enable_event_with_exclusions() create\endlink | |
1623 | \lt_var{ER} from some | |
1624 | \link #lttng_event recording event rule descriptor\endlink | |
1625 | \c event_rule (#lttng_event). | |
1626 | ||
1627 | <table> | |
1628 | <tr> | |
1629 | <th>Name | |
1630 | <th>Description | |
1631 | <tr> | |
1632 | <td> | |
1633 | \anchor api-rer-conds-inst-pt-type | |
1634 | \ref api-rer-conds-inst-pt-type "Instrumentation point type" | |
1635 | <td> | |
1636 | \lt_var{E} satisfies the instrumentation point type condition | |
1637 | of \lt_var{ER} if the instrumentation point from which LTTng | |
1638 | creates \lt_var{E} is, depending on the | |
1639 | \lt_obj_domain which contains \lt_var{ER}: | |
1640 | ||
1641 | <dl> | |
1642 | <dt>#LTTNG_DOMAIN_KERNEL | |
1643 | <dd> | |
1644 | Depending on | |
1645 | \link lttng_event::type <code>event_rule.type</code>\endlink: | |
1646 | ||
1647 | <dl> | |
1648 | <dt>#LTTNG_EVENT_TRACEPOINT | |
1649 | <dd> | |
1650 | An LTTng kernel tracepoint, that is, a statically | |
1651 | defined point in the source code of the kernel image | |
1652 | or of a kernel module with LTTng kernel tracer macros. | |
1653 | ||
1654 | @sa lttng_list_tracepoints() | |
1655 | ||
1656 | <dt>#LTTNG_EVENT_SYSCALL | |
1657 | <dd> | |
1658 | The entry and exit of a Linux kernel system call. | |
1659 | ||
1660 | @sa lttng_list_syscalls() | |
1661 | ||
1662 | <dt>#LTTNG_EVENT_PROBE | |
1663 | <dd> | |
1664 | A Linux | |
1665 | <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kprobe</a>, | |
1666 | that is, a single probe dynamically placed in the | |
1667 | compiled kernel code. | |
1668 | ||
1669 | \link lttng_event::lttng_event_attr_u::probe | |
1670 | <code>event_rule.attr.probe</code>\endlink | |
1671 | indicates the kprobe location, | |
1672 | while \link lttng_event::name | |
1673 | <code>event_rule.name</code>\endlink | |
1674 | is the name of the created kprobe instrumentation | |
1675 | point (future event name). | |
1676 | ||
1677 | The payload of a Linux kprobe event is empty. | |
1678 | ||
1679 | <dt>#LTTNG_EVENT_FUNCTION | |
1680 | <dd> | |
1681 | A Linux | |
1682 | <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kretprobe</a>, | |
1683 | that is, two probes dynamically placed at the entry | |
1684 | and exit of a function in the compiled kernel code. | |
1685 | ||
1686 | \link lttng_event::lttng_event_attr_u::probe | |
1687 | <code>event_rule.attr.probe</code>\endlink | |
1688 | indicates the kretprobe location, | |
1689 | while \link lttng_event::name | |
1690 | <code>event_rule.name</code>\endlink | |
1691 | is the name of the created kretprobe instrumentation | |
1692 | point (future event name). | |
1693 | ||
1694 | The payload of a Linux kretprobe event is empty. | |
1695 | ||
1696 | <dt>#LTTNG_EVENT_USERSPACE_PROBE | |
1697 | <dd> | |
1698 | A Linux | |
1699 | <a href="https://lwn.net/Articles/499190/">uprobe</a>, | |
1700 | that is, a single probe dynamically placed at the | |
1701 | entry of a compiled user space application/library | |
1702 | function through the kernel. | |
1703 | ||
1704 | Set and get the location of the uprobe with | |
1705 | lttng_event_set_userspace_probe_location() and | |
1706 | lttng_event_get_userspace_probe_location(). | |
1707 | ||
1708 | \link lttng_event::name <code>event_rule.name</code>\endlink | |
1709 | is the name of the created uprobe instrumentation | |
1710 | point (future event name). | |
1711 | ||
1712 | The payload of a Linux uprobe event is empty. | |
1713 | </dl> | |
1714 | ||
1715 | <dt>#LTTNG_DOMAIN_UST | |
1716 | <dd> | |
1717 | An LTTng user space tracepoint, that is, a statically | |
1718 | defined point in the source code of a C/C++ | |
1719 | application/library with LTTng user space tracer macros. | |
1720 | ||
1721 | \link lttng_event::type <code>event_rule.type</code>\endlink | |
1722 | must be #LTTNG_EVENT_TRACEPOINT. | |
1723 | ||
1724 | @sa lttng_list_tracepoints() | |
1725 | ||
1726 | <dt>#LTTNG_DOMAIN_JUL | |
1727 | <dt>#LTTNG_DOMAIN_LOG4J | |
1728 | <dt>#LTTNG_DOMAIN_PYTHON | |
1729 | <dd> | |
1730 | A Java/Python logging statement. | |
1731 | ||
1732 | \link lttng_event::type <code>event_rule.type</code>\endlink | |
1733 | must be #LTTNG_EVENT_TRACEPOINT. | |
1734 | ||
1735 | @sa lttng_list_tracepoints() | |
1736 | </dl> | |
1737 | <tr> | |
1738 | <td> | |
1739 | \anchor api-rer-conds-event-name | |
1740 | \ref api-rer-conds-event-name "Event name" | |
1741 | <td> | |
1742 | An event \lt_var{E} satisfies the event name condition | |
1743 | of \lt_var{ER} if the two following statements are | |
1744 | \b true: | |
1745 | ||
1746 | - \link lttng_event::name <code>event_rule.name</code>\endlink | |
1747 | matches, depending on | |
1748 | \link lttng_event::type <code>event_rule.type</code>\endlink | |
1749 | (see \ref api-rer-conds-inst-pt-type "Instrumentation point type" | |
1750 | above): | |
1751 | ||
1752 | <dl> | |
1753 | <dt>#LTTNG_EVENT_TRACEPOINT | |
1754 | <dd> | |
1755 | The full name of the LTTng tracepoint or Java/Python | |
1756 | logger from which LTTng creates \lt_var{E}. | |
1757 | ||
1758 | Note that the full name of a | |
1759 | \link #LTTNG_DOMAIN_UST user space\endlink tracepoint is | |
1760 | <code><em>PROVIDER</em>:<em>NAME</em></code>, where | |
1761 | <code><em>PROVIDER</em></code> is the tracepoint | |
1762 | provider name and <code><em>NAME</em></code> is the | |
1763 | tracepoint name. | |
1764 | ||
1765 | <dt>#LTTNG_EVENT_SYSCALL | |
1766 | <dd> | |
1767 | The name of the system call, without any | |
1768 | <code>sys_</code> prefix, from which LTTng | |
1769 | creates \lt_var{E}. | |
1770 | </dl> | |
1771 | ||
1772 | @sa \ref api-rer-er-name "Event record name". | |
1773 | ||
1774 | - If the \lt_obj_domain | |
1775 | containing \lt_var{ER} is #LTTNG_DOMAIN_UST: | |
1776 | none of the event name exclusion patterns of | |
1777 | \c event_rule matches the full name of the user | |
1778 | space tracepoint from which LTTng creates \lt_var{E}. | |
1779 | ||
1780 | Set the event name exclusion patterns of | |
1781 | \c event_rule when you call | |
1782 | lttng_enable_event_with_exclusions(). | |
1783 | ||
1784 | Get the event name exclusion patterns of | |
1785 | a recording event rule descriptor with | |
1786 | lttng_event_get_exclusion_name_count() and | |
1787 | lttng_event_get_exclusion_name(). | |
1788 | ||
1789 | This condition is only meaningful when | |
1790 | \link lttng_event::type <code>event_rule.type</code>\endlink | |
1791 | is #LTTNG_EVENT_TRACEPOINT or | |
1792 | #LTTNG_EVENT_SYSCALL: it's always satisfied for the other | |
1793 | \ref api-rer-conds-inst-pt-type "instrumentation point types". | |
1794 | ||
1795 | In all cases, | |
1796 | \link lttng_event::name <code>event_rule.name</code>\endlink | |
1797 | and the event name exclusion patterns of | |
1798 | \c event_rule are <em>globbing patterns</em>: the | |
1799 | <code>*</code> character means "match anything". To match a | |
1800 | literal <code>*</code> character, use <code>\\*</code>. | |
1801 | <tr> | |
1802 | <td> | |
1803 | \anchor api-rer-conds-ll | |
1804 | \ref api-rer-conds-ll "Instrumentation point log level" | |
1805 | <td> | |
1806 | An event \lt_var{E} satisfies the instrumentation point | |
1807 | log level condition of \lt_var{ER} if, depending on | |
1808 | \link lttng_event::loglevel_type <code>event_rule.loglevel_type</code>\endlink, | |
1809 | the log level of the LTTng user space tracepoint or | |
1810 | logging statement from which LTTng creates \lt_var{E} | |
1811 | is: | |
1812 | ||
1813 | <dl> | |
1814 | <dt>#LTTNG_EVENT_LOGLEVEL_ALL | |
1815 | <dd> | |
1816 | Anything (the condition is always satisfied). | |
1817 | ||
1818 | <dt>#LTTNG_EVENT_LOGLEVEL_RANGE | |
1819 | <dd> | |
1820 | At least as severe as | |
1821 | \link lttng_event::loglevel <code>event_rule.loglevel</code>\endlink. | |
1822 | ||
1823 | <dt>#LTTNG_EVENT_LOGLEVEL_SINGLE | |
1824 | <dd> | |
1825 | Exactly | |
1826 | \link lttng_event::loglevel <code>event_rule.loglevel</code>\endlink. | |
1827 | </dl> | |
1828 | ||
1829 | This condition is only meaningful when the \lt_obj_domain | |
1830 | containing \lt_var{ER} is \em not #LTTNG_DOMAIN_KERNEL: | |
1831 | it's always satisfied for #LTTNG_DOMAIN_KERNEL. | |
1832 | <tr> | |
1833 | <td> | |
1834 | \anchor api-rer-conds-filter | |
1835 | \ref api-rer-conds-filter "Event payload and context filter" | |
1836 | <td> | |
1837 | An event \lt_var{E} satisfies the event payload and | |
1838 | context filter condition of \lt_var{ER} if | |
1839 | \c event_rule has no filter expression or if its filter | |
1840 | expression \lt_var{EXPR} evaluates to \b true | |
1841 | when LTTng creates \lt_var{E}. | |
1842 | ||
1843 | This condition is only meaningful when: | |
1844 | ||
1845 | - The \lt_obj_domain containing \lt_var{ER} is | |
1846 | #LTTNG_DOMAIN_KERNEL or #LTTNG_DOMAIN_UST: it's always | |
1847 | satisfied for the other tracing domains. | |
1848 | ||
1849 | - \link lttng_event::type <code>event_rule.type</code>\endlink | |
1850 | is #LTTNG_EVENT_TRACEPOINT or #LTTNG_EVENT_SYSCALL: | |
1851 | it's always satisfied for the other | |
1852 | \ref api-rer-conds-inst-pt-type "instrumentation point types". | |
1853 | ||
1854 | Set the event payload and context filter expression of | |
1855 | \c event_rule when you call | |
1856 | lttng_enable_event_with_exclusions(). | |
1857 | ||
1858 | Get the event payload and context filter expression of | |
1859 | a recording event rule descriptor with | |
1860 | lttng_event_get_filter_expression(). | |
1861 | ||
1862 | \lt_var{EXPR} can contain references to the payload fields | |
1863 | of \lt_var{E} and to the current | |
1864 | \link #lttng_event_context_type context\endlink fields. | |
1865 | ||
1866 | The expected syntax of \lt_var{EXPR} is similar to the syntax | |
1867 | of a C language conditional expression (an expression | |
1868 | which an \c if statement can evaluate), but there are a few | |
1869 | differences: | |
1870 | ||
1871 | - A <code><em>NAME</em></code> expression identifies an event | |
1872 | payload field named <code><em>NAME</em></code> (a | |
1873 | C identifier). | |
1874 | ||
1875 | Use the C language dot and square bracket notations to | |
1876 | access nested structure and array/sequence fields. You can | |
1877 | only use a constant, positive integer number within square | |
1878 | brackets. If the index is out of bounds, \lt_var{EXPR} is | |
1879 | \b false. | |
1880 | ||
1881 | The value of an enumeration field is an integer. | |
1882 | ||
1883 | When a field expression doesn't exist, \lt_var{EXPR} is | |
1884 | \b false. | |
1885 | ||
1886 | Examples: <code>my_field</code>, <code>target_cpu</code>, | |
1887 | <code>seq[7]</code>, <code>msg.user[1].data[2][17]</code>. | |
1888 | ||
1889 | - A <code>$ctx.<em>TYPE</em></code> expression identifies the | |
1890 | statically-known context field having the type | |
1891 | <code><em>TYPE</em></code> (a C identifier). | |
1892 | ||
1893 | When a field expression doesn't exist, \lt_var{EXPR} is \b | |
1894 | false. | |
1895 | ||
1896 | Examples: <code>$ctx.prio</code>, | |
1897 | <code>$ctx.preemptible</code>, | |
1898 | <code>$ctx.perf:cpu:stalled-cycles-frontend</code>. | |
1899 | ||
1900 | - A <code>$app.<em>PROVIDER</em>:<em>TYPE</em></code> | |
1901 | expression identifies the application-specific context field | |
1902 | having the type <code><em>TYPE</em></code> (a | |
1903 | C identifier) from the provider | |
1904 | <code><em>PROVIDER</em></code> (a C identifier). | |
1905 | ||
1906 | When a field expression doesn't exist, \lt_var{EXPR} is \b | |
1907 | false. | |
1908 | ||
1909 | Example: <code>$app.server:cur_user</code>. | |
1910 | ||
1911 | - Compare strings, either string fields or string literals | |
1912 | (double-quoted), with the <code>==</code> and | |
1913 | <code>!=</code> operators. | |
1914 | ||
1915 | When comparing to a string literal, the <code>*</code> | |
1916 | character means "match anything". To match a literal | |
1917 | <code>*</code> character, use <code>\\*</code>. | |
1918 | ||
1919 | Examples: <code>my_field == "user34"</code>, | |
1920 | <code>my_field == my_other_field</code>, | |
1921 | <code>my_field == "192.168.*"</code>. | |
1922 | ||
1923 | - The | |
1924 | <a href="https://en.wikipedia.org/wiki/Order_of_operations">precedence table</a> | |
1925 | of the operators which are supported in | |
1926 | \lt_var{EXPR} is as follows. In this table, the highest | |
1927 | precedence is 1: | |
1928 | ||
1929 | <table> | |
1930 | <tr> | |
1931 | <th>Precedence | |
1932 | <th>Operator | |
1933 | <th>Description | |
1934 | <th>Associativity | |
1935 | <tr> | |
1936 | <td>1 | |
1937 | <td><code>-</code> | |
1938 | <td>Unary minus | |
1939 | <td>Right-to-left | |
1940 | <tr> | |
1941 | <td>1 | |
1942 | <td><code>+</code> | |
1943 | <td>Unary plus | |
1944 | <td>Right-to-left | |
1945 | <tr> | |
1946 | <td>1 | |
1947 | <td><code>!</code> | |
1948 | <td>Logical NOT | |
1949 | <td>Right-to-left | |
1950 | <tr> | |
1951 | <td>1 | |
1952 | <td><code>~</code> | |
1953 | <td>Bitwise NOT | |
1954 | <td>Right-to-left | |
1955 | <tr> | |
1956 | <td>2 | |
1957 | <td><code><<</code> | |
1958 | <td>Bitwise left shift | |
1959 | <td>Left-to-right | |
1960 | <tr> | |
1961 | <td>2 | |
1962 | <td><code>>></code> | |
1963 | <td>Bitwise right shift | |
1964 | <td>Left-to-right | |
1965 | <tr> | |
1966 | <td>3 | |
1967 | <td><code>&</code> | |
1968 | <td>Bitwise AND | |
1969 | <td>Left-to-right | |
1970 | <tr> | |
1971 | <td>4 | |
1972 | <td><code>^</code> | |
1973 | <td>Bitwise XOR | |
1974 | <td>Left-to-right | |
1975 | <tr> | |
1976 | <td>5 | |
1977 | <td><code>|</code> | |
1978 | <td>Bitwise OR | |
1979 | <td>Left-to-right | |
1980 | <tr> | |
1981 | <td>6 | |
1982 | <td><code><</code> | |
1983 | <td>Less than | |
1984 | <td>Left-to-right | |
1985 | <tr> | |
1986 | <td>6 | |
1987 | <td><code><=</code> | |
1988 | <td>Less than or equal to | |
1989 | <td>Left-to-right | |
1990 | <tr> | |
1991 | <td>6 | |
1992 | <td><code>></code> | |
1993 | <td>Greater than | |
1994 | <td>Left-to-right | |
1995 | <tr> | |
1996 | <td>6 | |
1997 | <td><code>>=</code> | |
1998 | <td>Greater than or equal to | |
1999 | <td>Left-to-right | |
2000 | <tr> | |
2001 | <td>7 | |
2002 | <td><code>==</code> | |
2003 | <td>Equal to | |
2004 | <td>Left-to-right | |
2005 | <tr> | |
2006 | <td>7 | |
2007 | <td><code>!=</code> | |
2008 | <td>Not equal to | |
2009 | <td>Left-to-right | |
2010 | <tr> | |
2011 | <td>8 | |
2012 | <td><code>&&</code> | |
2013 | <td>Logical AND | |
2014 | <td>Left-to-right | |
2015 | <tr> | |
2016 | <td>9 | |
2017 | <td><code>||</code> | |
2018 | <td>Logical OR | |
2019 | <td>Left-to-right | |
2020 | </table> | |
2021 | ||
2022 | Parentheses are supported to bypass the default order. | |
2023 | ||
2024 | @attention | |
2025 | Unlike the C language, the bitwise AND and OR | |
2026 | operators (<code>&</code> and <code>|</code>) in | |
2027 | \lt_var{EXPR} take precedence over relational | |
2028 | operators (<code><<</code>, <code><=</code>, | |
2029 | <code>></code>, <code>>=</code>, <code>==</code>, | |
2030 | and <code>!=</code>). This means the expression | |
2031 | <code>2 & 2 == 2</code> | |
2032 | is \b true while the equivalent C expression | |
2033 | is \b false. | |
2034 | ||
2035 | The arithmetic operators are :not: supported. | |
2036 | ||
2037 | LTTng first casts all integer constants and fields to signed | |
2038 | 64-bit integers. The representation of negative integers is | |
2039 | two's complement. This means that, for example, the signed | |
2040 | 8-bit integer field 0xff (-1) becomes 0xffffffffffffffff | |
2041 | (still -1) once casted. | |
2042 | ||
2043 | Before a bitwise operator is applied, LTTng casts all its | |
2044 | operands to unsigned 64-bit integers, and then casts the | |
2045 | result back to a signed 64-bit integer. For the bitwise NOT | |
2046 | operator, it's the equivalent of this C expression: | |
2047 | ||
2048 | @code | |
2049 | (int64_t) ~((uint64_t) val) | |
2050 | @endcode | |
2051 | ||
2052 | For the binary bitwise operators, it's the equivalent of those | |
2053 | C expressions: | |
2054 | ||
2055 | @code | |
2056 | (int64_t) ((uint64_t) lhs >> (uint64_t) rhs) | |
2057 | (int64_t) ((uint64_t) lhs << (uint64_t) rhs) | |
2058 | (int64_t) ((uint64_t) lhs & (uint64_t) rhs) | |
2059 | (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs) | |
2060 | (int64_t) ((uint64_t) lhs | (uint64_t) rhs) | |
2061 | @endcode | |
2062 | ||
2063 | If the right-hand side of a bitwise shift operator | |
2064 | (<code><<</code> and <code>>></code>) is not in | |
2065 | the [0, 63] range, then \lt_var{EXPR} is \b false. | |
2066 | ||
2067 | @note | |
2068 | See the \ref api_pais to allow or disallow processes to | |
2069 | record LTTng events based on their attributes | |
2070 | instead of using equivalent statically-known context | |
2071 | fields in \lt_var{EXPR} like <code>$ctx.pid</code>. | |
2072 | The former method is much more efficient. | |
2073 | ||
2074 | \lt_var{EXPR} examples: | |
2075 | ||
2076 | @code{.unparsed} | |
2077 | msg_id == 23 && size >= 2048 | |
2078 | @endcode | |
2079 | ||
2080 | @code{.unparsed} | |
2081 | $ctx.procname == "lttng*" && (!flag || poel < 34) | |
2082 | @endcode | |
2083 | ||
2084 | @code{.unparsed} | |
2085 | $app.my_provider:my_context == 17.34e9 || some_enum >= 14 | |
2086 | @endcode | |
2087 | ||
2088 | @code{.unparsed} | |
2089 | $ctx.cpu_id == 2 && filename != "*.log" | |
2090 | @endcode | |
2091 | ||
2092 | @code{.unparsed} | |
2093 | eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234 | |
2094 | @endcode | |
2095 | </table> | |
2096 | ||
2097 | <dt>Implicit conditions | |
2098 | <dd> | |
2099 | - \lt_var{ER} itself is \link lttng_event::enabled enabled\endlink. | |
2100 | ||
2101 | A recording event rule is enabled on | |
2102 | \link lttng_enable_event_with_exclusions() creation\endlink. | |
2103 | ||
2104 | @sa lttng_enable_event() -- | |
2105 | Creates or enables a recording event rule. | |
2106 | @sa lttng_disable_event_ext() -- | |
2107 | Disables a recording event rule. | |
2108 | ||
2109 | - The \lt_obj_channel which contains \lt_var{ER} is | |
2110 | \link lttng_channel::enabled enabled\endlink. | |
2111 | ||
2112 | A channel is enabled on | |
2113 | \link lttng_enable_channel() creation\endlink. | |
2114 | ||
2115 | @sa lttng_enable_channel() -- | |
2116 | Creates or enables a channel. | |
2117 | @sa lttng_disable_channel() -- | |
2118 | Disables a channel. | |
2119 | ||
2120 | - The \lt_obj_session which contains \lt_var{ER} is | |
2121 | \link lttng_session::enabled active\endlink (started). | |
2122 | ||
2123 | A recording session is inactive (stopped) on | |
2124 | \link lttng_create_session_ext() creation\endlink. | |
2125 | ||
2126 | @sa lttng_start_tracing() -- | |
2127 | Starts a recording session. | |
2128 | @sa lttng_stop_tracing() -- | |
2129 | Stops a recording session. | |
2130 | ||
2131 | - The process for which LTTng creates \lt_var{E} is | |
2132 | \ref api_pais "allowed to record events". | |
2133 | ||
2134 | All processes are allowed to record events on recording session | |
2135 | \link lttng_create_session_ext() creation\endlink. | |
2136 | </dl> | |
2137 | ||
2138 | <h1>\anchor api-rer-er-name Event record name</h1> | |
2139 | ||
2140 | When LTTng records an event \lt_var{E}, the resulting event record | |
2141 | has a name which depends on the | |
2142 | \ref api-rer-conds-inst-pt-type "instrumentation point type condition" | |
2143 | of the recording event rule \lt_var{ER} which matched \lt_var{E} | |
2144 | as well as on the \lt_obj_domain which contains \lt_var{ER}: | |
2145 | ||
2146 | <table> | |
2147 | <tr> | |
2148 | <th>Tracing domain | |
2149 | <th>Instrumentation point type | |
2150 | <th>Event record name | |
2151 | <tr> | |
2152 | <td>#LTTNG_DOMAIN_KERNEL or #LTTNG_DOMAIN_UST | |
2153 | <td>#LTTNG_EVENT_TRACEPOINT | |
2154 | <td> | |
2155 | Full name of the tracepoint from which LTTng creates \lt_var{E}. | |
2156 | ||
2157 | Note that the full name of a | |
2158 | \link #LTTNG_DOMAIN_UST user space\endlink tracepoint is | |
2159 | <code><em>PROVIDER</em>:<em>NAME</em></code>, where | |
2160 | <code><em>PROVIDER</em></code> is the tracepoint provider name and | |
2161 | <code><em>NAME</em></code> is the tracepoint name. | |
2162 | <tr> | |
2163 | <td>#LTTNG_DOMAIN_JUL | |
2164 | <td>#LTTNG_EVENT_TRACEPOINT | |
2165 | <td> | |
2166 | <code>lttng_jul:event</code> | |
2167 | ||
2168 | Such an event record has a string field <code>logger_name</code> | |
2169 | which contains the name of the <code>java.util.logging</code> | |
2170 | logger from which LTTng creates \lt_var{E}. | |
2171 | <tr> | |
2172 | <td>#LTTNG_DOMAIN_LOG4J | |
2173 | <td>#LTTNG_EVENT_TRACEPOINT | |
2174 | <td> | |
2175 | <code>lttng_log4j:event</code> | |
2176 | ||
2177 | Such an event record has a string field <code>logger_name</code> | |
2178 | which contains the name of the Apache log4j logger from which | |
2179 | LTTng creates \lt_var{E}. | |
2180 | <tr> | |
2181 | <td>#LTTNG_DOMAIN_PYTHON | |
2182 | <td>#LTTNG_EVENT_TRACEPOINT | |
2183 | <td> | |
2184 | <code>lttng_python:event</code> | |
2185 | ||
2186 | Such an event record has a string field <code>logger_name</code> | |
2187 | which contains the name of the Python logger from which LTTng | |
2188 | creates \lt_var{E}. | |
2189 | <tr> | |
2190 | <td>#LTTNG_DOMAIN_KERNEL | |
2191 | <td>#LTTNG_EVENT_SYSCALL | |
2192 | <td> | |
2193 | Location: | |
2194 | ||
2195 | <dl> | |
2196 | <dt>Entry | |
2197 | <dd> | |
2198 | <code>syscall_entry_<em>NAME</em></code>, where | |
2199 | <code><em>NAME</em></code> is the name of the system call from | |
2200 | which LTTng creates \lt_var{E}, without any | |
2201 | <code>sys_</code> prefix. | |
2202 | ||
2203 | <dt>Exit | |
2204 | <dd> | |
2205 | <code>syscall_exit_<em>NAME</em></code>, where | |
2206 | <code><em>NAME</em></code> is the name of the system call from | |
2207 | which LTTng creates \lt_var{E}, without any | |
2208 | <code>sys_</code> prefix. | |
2209 | </dl> | |
2210 | <tr> | |
2211 | <td>#LTTNG_DOMAIN_KERNEL | |
2212 | <td>#LTTNG_EVENT_PROBE or #LTTNG_EVENT_USERSPACE_PROBE | |
2213 | <td> | |
2214 | The lttng_event::name member of the | |
2215 | descriptor you used to create \lt_var{ER} with | |
2216 | lttng_enable_event_with_exclusions(). | |
2217 | <tr> | |
2218 | <td>#LTTNG_DOMAIN_KERNEL | |
2219 | <td>#LTTNG_EVENT_FUNCTION | |
2220 | <td> | |
2221 | Location: | |
2222 | ||
2223 | <dl> | |
2224 | <dt>Entry | |
2225 | <dd><code><em>NAME</em>_entry</code> | |
2226 | ||
2227 | <dt>Exit | |
2228 | <dd><code><em>NAME</em>_exit</code> | |
2229 | </dl> | |
2230 | ||
2231 | where <code><em>NAME</em></code> is the lttng_event::name member | |
2232 | of the descriptor you used to create | |
2233 | \lt_var{ER} with lttng_enable_event_with_exclusions(). | |
2234 | </table> | |
2235 | ||
2236 | @defgroup api_pais Process attribute inclusion set API | |
2237 | @ingroup api_session | |
2238 | ||
2239 | To be done. | |
2240 | ||
2241 | @defgroup api_session_clear Recording session clearing API | |
2242 | @ingroup api_session | |
2243 | ||
2244 | This API makes it possible to clear a \lt_obj_session, that is, to | |
2245 | delete the contents of its tracing buffers and/or of all its | |
2246 | \ref api-session-local-mode "local" and | |
2247 | \ref api-session-net-mode "streamed" trace data. | |
2248 | ||
2249 | To clear a recording session: | |
2250 | ||
2251 | -# Call lttng_clear_session(), passing the name of the recording session | |
2252 | to clear. | |
2253 | ||
2254 | This function initiates a clearing operation, returning immediately. | |
2255 | ||
2256 | This function can set a pointer to a | |
2257 | \link #lttng_clear_handle clearing handle\endlink | |
2258 | so that you can wait for the completion of the | |
2259 | operation. Without such a handle, you can't know when the clearing | |
2260 | operation completes and whether or not it does successfully. | |
2261 | ||
2262 | -# <strong>If you have a clearing handle from step 1</strong>: | |
2263 | ||
2264 | -# Call lttng_clear_handle_wait_for_completion() to wait for the | |
2265 | completion of the clearing operation. | |
2266 | ||
2267 | -# Call lttng_clear_handle_get_result() to get whether or not the | |
2268 | clearing operation successfully completed. | |
2269 | ||
2270 | -# Destroy the clearing handle with lttng_clear_handle_destroy(). | |
2271 | ||
2272 | @sa \lt_man{lttng-clear,1} | |
2273 | ||
2274 | @defgroup api_session_snapshot Recording session snapshot API | |
2275 | @ingroup api_session | |
2276 | ||
2277 | To be done. | |
2278 | ||
2279 | @defgroup api_session_rotation Recording session rotation API | |
2280 | @ingroup api_session | |
2281 | ||
2282 | To be done. | |
2283 | ||
2284 | @defgroup api_session_save_load Recording session saving and loading API | |
2285 | @ingroup api_session | |
2286 | ||
2287 | To be done. | |
2288 | ||
2289 | @defgroup api_inst_pt Instrumentation point listing API | |
2290 | ||
2291 | The lttng_list_tracepoints() and lttng_list_syscalls() functions set a | |
2292 | pointer to an array of | |
2293 | <strong><em>\ref api-rer-inst-pt-descr "instrumentation point descriptors"</em></strong>. | |
2294 | ||
2295 | With those two functions, you can get details about the available | |
2296 | LTTng tracepoints, Java/Python loggers, and Linux kernel system calls, | |
2297 | as long as you can | |
2298 | \ref api-gen-sessiond-conn "connect to a session daemon". | |
2299 | You can then use the discovered information to create corresponding | |
2300 | \lt_obj_rers so that you can record the events | |
2301 | which LTTng creates from instrumentation points. | |
2302 | ||
2303 | See \ref api_rer to learn more about instrumentation points, events, | |
2304 | event records, and recording event rules. | |
2305 | ||
2306 | @defgroup api_trigger Trigger API | |
2307 | ||
2308 | To be done. | |
2309 | ||
2310 | @defgroup api_trigger_cond Trigger condition API | |
2311 | @ingroup api_trigger | |
2312 | ||
2313 | To be done. | |
2314 | ||
2315 | @defgroup api_trigger_cond_er_matches "Event rule matches" trigger condition API | |
2316 | @ingroup api_trigger_cond | |
2317 | ||
2318 | To be done. | |
2319 | ||
2320 | @defgroup api_er Event rule API | |
2321 | @ingroup api_trigger_cond_er_matches | |
2322 | ||
2323 | To be done. | |
2324 | ||
2325 | @defgroup api_ll_rule Log level rule API | |
2326 | @ingroup api_er | |
2327 | ||
2328 | To be done. | |
2329 | ||
2330 | @defgroup api_ev_expr Event expression API | |
2331 | @ingroup api_trigger_cond_er_matches | |
2332 | ||
2333 | To be done. | |
2334 | ||
2335 | @defgroup api_ev_field_val Event field value API | |
2336 | @ingroup api_trigger_cond_er_matches | |
2337 | ||
2338 | To be done. | |
2339 | ||
2340 | @defgroup api_trigger_action Trigger action API | |
2341 | @ingroup api_trigger | |
2342 | ||
2343 | To be done. | |
2344 | ||
2345 | @defgroup api_notif Notification API | |
2346 | @ingroup api_trigger_action | |
2347 | ||
2348 | To be done. | |
2349 | ||
2350 | @defgroup api_error Error query API | |
2351 | ||
2352 | To be done. | |
2353 | */ |