| 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 | */ |