| 1 | /* |
| 2 | * lttng.h |
| 3 | * |
| 4 | * Linux Trace Toolkit Control Library Header File |
| 5 | * |
| 6 | * Copyright (C) 2011 EfficiOS Inc. |
| 7 | * |
| 8 | * SPDX-License-Identifier: LGPL-2.1-only |
| 9 | * |
| 10 | */ |
| 11 | |
| 12 | #ifndef LTTNG_H |
| 13 | #define LTTNG_H |
| 14 | |
| 15 | #include <lttng/lttng-export.h> |
| 16 | |
| 17 | /* Error codes that can be returned by API calls */ |
| 18 | #include <lttng/lttng-error.h> |
| 19 | |
| 20 | /* Include every LTTng ABI/API available. */ |
| 21 | #include <lttng/action/action.h> |
| 22 | #include <lttng/action/list.h> |
| 23 | #include <lttng/action/notify.h> |
| 24 | #include <lttng/action/path.h> |
| 25 | #include <lttng/action/rate-policy.h> |
| 26 | #include <lttng/action/rotate-session.h> |
| 27 | #include <lttng/action/snapshot-session.h> |
| 28 | #include <lttng/action/start-session.h> |
| 29 | #include <lttng/action/stop-session.h> |
| 30 | #include <lttng/channel.h> |
| 31 | #include <lttng/clear-handle.h> |
| 32 | #include <lttng/clear.h> |
| 33 | #include <lttng/condition/buffer-usage.h> |
| 34 | #include <lttng/condition/condition.h> |
| 35 | #include <lttng/condition/evaluation.h> |
| 36 | #include <lttng/condition/event-rule-matches.h> |
| 37 | #include <lttng/condition/session-consumed-size.h> |
| 38 | #include <lttng/condition/session-rotation.h> |
| 39 | #include <lttng/constant.h> |
| 40 | #include <lttng/destruction-handle.h> |
| 41 | #include <lttng/domain.h> |
| 42 | #include <lttng/endpoint.h> |
| 43 | #include <lttng/error-query.h> |
| 44 | #include <lttng/event-expr.h> |
| 45 | #include <lttng/event-field-value.h> |
| 46 | #include <lttng/event-rule/event-rule.h> |
| 47 | #include <lttng/event-rule/jul-logging.h> |
| 48 | #include <lttng/event-rule/kernel-kprobe.h> |
| 49 | #include <lttng/event-rule/kernel-syscall.h> |
| 50 | #include <lttng/event-rule/kernel-tracepoint.h> |
| 51 | #include <lttng/event-rule/kernel-uprobe.h> |
| 52 | #include <lttng/event-rule/log4j-logging.h> |
| 53 | #include <lttng/event-rule/python-logging.h> |
| 54 | #include <lttng/event-rule/user-tracepoint.h> |
| 55 | #include <lttng/event.h> |
| 56 | #include <lttng/handle.h> |
| 57 | #include <lttng/health.h> |
| 58 | #include <lttng/kernel-probe.h> |
| 59 | #include <lttng/kernel.h> |
| 60 | #include <lttng/load.h> |
| 61 | #include <lttng/location.h> |
| 62 | #include <lttng/log-level-rule.h> |
| 63 | #include <lttng/lttng-error.h> |
| 64 | #include <lttng/notification/channel.h> |
| 65 | #include <lttng/notification/notification.h> |
| 66 | #include <lttng/rotation.h> |
| 67 | #include <lttng/save.h> |
| 68 | #include <lttng/session-descriptor.h> |
| 69 | #include <lttng/session.h> |
| 70 | #include <lttng/snapshot.h> |
| 71 | #include <lttng/tracker.h> |
| 72 | #include <lttng/trigger/trigger.h> |
| 73 | #include <lttng/userspace-probe.h> |
| 74 | |
| 75 | #ifdef __cplusplus |
| 76 | extern "C" { |
| 77 | #endif |
| 78 | |
| 79 | enum lttng_calibrate_type { |
| 80 | LTTNG_CALIBRATE_FUNCTION = 0, |
| 81 | }; |
| 82 | |
| 83 | /* Machine interface output type */ |
| 84 | enum lttng_mi_output_type { |
| 85 | LTTNG_MI_XML = 1 /* XML output */ |
| 86 | }; |
| 87 | |
| 88 | #define LTTNG_CALIBRATE_PADDING1 16 |
| 89 | struct lttng_calibrate { |
| 90 | enum lttng_calibrate_type type; |
| 91 | |
| 92 | char padding[LTTNG_CALIBRATE_PADDING1]; |
| 93 | }; |
| 94 | |
| 95 | /*! |
| 96 | @brief |
| 97 | Returns whether or not liblttng-ctl is able to connect to a |
| 98 | listening session daemon. |
| 99 | |
| 100 | @ingroup api_gen |
| 101 | |
| 102 | How this function tries to |
| 103 | \ref api-gen-sessiond-conn "connect to a session daemon" depends on the |
| 104 | current Unix tracing group (initially \c tracing) of the library. Set |
| 105 | the tracing group with lttng_set_tracing_group(). |
| 106 | |
| 107 | @returns |
| 108 | @parblock |
| 109 | One of: |
| 110 | |
| 111 | <dl> |
| 112 | <dt>1</dt> |
| 113 | <dd> |
| 114 | liblttng-ctl is able to connect to a session daemon. |
| 115 | |
| 116 | <dt>0 |
| 117 | <dd> |
| 118 | liblttng-ctl isn't able to connect to a session daemon. |
| 119 | |
| 120 | <dt>Negative value |
| 121 | <dd> |
| 122 | Error: a negative #lttng_error_code enumerator. |
| 123 | </dl> |
| 124 | @endparblock |
| 125 | |
| 126 | @sa lttng_set_tracing_group() -- |
| 127 | Sets the current Unix tracing group of liblttng-ctl. |
| 128 | */ |
| 129 | LTTNG_EXPORT extern int lttng_session_daemon_alive(void); |
| 130 | |
| 131 | /*! |
| 132 | @brief |
| 133 | Sets the current Unix tracing group of liblttng-ctl to \lt_p{group}. |
| 134 | |
| 135 | @ingroup api_gen |
| 136 | |
| 137 | How the liblttng-ctl functions |
| 138 | \ref api-gen-sessiond-conn "connect to a session daemon" depends on |
| 139 | the current Unix tracing group (initially \c tracing) of the library. |
| 140 | |
| 141 | @param[in] group |
| 142 | New Unix tracing group of liblttng-ctl. |
| 143 | |
| 144 | @returns |
| 145 | 0 on success, or a \em negative #lttng_error_code enumerator |
| 146 | otherwise. |
| 147 | |
| 148 | @lt_pre_not_null{group} |
| 149 | @pre |
| 150 | \lt_p{group} names an existing Unix group. |
| 151 | */ |
| 152 | LTTNG_EXPORT extern int lttng_set_tracing_group(const char *group); |
| 153 | |
| 154 | /* |
| 155 | * This call registers an "outside consumer" for a session and an lttng domain. |
| 156 | * No consumer will be spawned and all fds/commands will go through the socket |
| 157 | * path given (socket_path). |
| 158 | * |
| 159 | * NOTE that this is not recommended unless you absolutely know what you are |
| 160 | * doing. |
| 161 | * |
| 162 | * Return 0 on success else a negative LTTng error code. |
| 163 | */ |
| 164 | LTTNG_EXPORT extern int lttng_register_consumer(struct lttng_handle *handle, |
| 165 | const char *socket_path); |
| 166 | |
| 167 | /*! |
| 168 | @brief |
| 169 | Makes the recording session named \lt_p{session_name} active, |
| 170 | starting all the tracers for its |
| 171 | \ref api-channel-channel "channels". |
| 172 | |
| 173 | @ingroup api_session |
| 174 | |
| 175 | @note |
| 176 | An #LTTNG_ACTION_TYPE_START_SESSION trigger action can also activate |
| 177 | (start) a recording session. |
| 178 | |
| 179 | @param[in] session_name |
| 180 | Name of the recording session to activate/start. |
| 181 | |
| 182 | @returns |
| 183 | 0 on success, or a \em negative #lttng_error_code enumerator |
| 184 | otherwise. |
| 185 | |
| 186 | @lt_pre_conn |
| 187 | @lt_pre_not_null{session_name} |
| 188 | @lt_pre_sess_exists{session_name} |
| 189 | @lt_pre_sess_inactive{session_name} |
| 190 | |
| 191 | @sa lttng_stop_tracing() -- |
| 192 | Stops a recording session. |
| 193 | @sa \lt_man{lttng-start,1} |
| 194 | */ |
| 195 | LTTNG_EXPORT extern int lttng_start_tracing(const char *session_name); |
| 196 | |
| 197 | /*! |
| 198 | @brief |
| 199 | Makes the recording session named \lt_p{session_name} inactive, |
| 200 | stopping all the tracers for its |
| 201 | \ref api-channel-channel "channels", blocking until the operation |
| 202 | completes. |
| 203 | |
| 204 | @ingroup api_session |
| 205 | |
| 206 | This function blocks until the trace data of the |
| 207 | recording session named \lt_p{session_name} is valid. Use |
| 208 | lttng_stop_tracing_no_wait() to avoid a blocking call. |
| 209 | |
| 210 | If LTTng \ref api_session_rotation "archived the current trace chunk" |
| 211 | of the recording session named \lt_p{session_name} at least |
| 212 | once during its lifetime, then this function renames the current trace |
| 213 | chunk subdirectory. Although it's safe to |
| 214 | read the content of this renamed subdirectory while the recording |
| 215 | session remains inactive, it's \em not a trace chunk archive: you need to |
| 216 | \link lttng_destroy_session_ext() destroy\endlink the recording session |
| 217 | or a rotation needs to occur to archive it. |
| 218 | |
| 219 | @note |
| 220 | An #LTTNG_ACTION_TYPE_STOP_SESSION trigger action can also |
| 221 | deactivate (stop) a recording session. |
| 222 | |
| 223 | @param[in] session_name |
| 224 | Name of the recording session to deactivate/stop. |
| 225 | |
| 226 | @returns |
| 227 | 0 on success, or a \em negative #lttng_error_code enumerator |
| 228 | otherwise. |
| 229 | |
| 230 | @lt_pre_conn |
| 231 | @lt_pre_not_null{session_name} |
| 232 | @lt_pre_sess_exists{session_name} |
| 233 | @lt_pre_sess_active{session_name} |
| 234 | |
| 235 | @sa lttng_stop_tracing_no_wait() -- |
| 236 | Deactivates a recording session without waiting for the operation |
| 237 | to complete. |
| 238 | @sa lttng_start_tracing() -- |
| 239 | Starts a recording session. |
| 240 | @sa \lt_man{lttng-stop,1} |
| 241 | */ |
| 242 | LTTNG_EXPORT extern int lttng_stop_tracing(const char *session_name); |
| 243 | |
| 244 | /*! |
| 245 | @brief |
| 246 | Makes the recording session named \lt_p{session_name} inactive, |
| 247 | stopping all the tracers for its |
| 248 | \ref api-channel-channel "channels" without waiting for the |
| 249 | operation to complete. |
| 250 | |
| 251 | @ingroup api_session |
| 252 | |
| 253 | Unlike lttng_stop_tracing(), this function does \em not block until |
| 254 | the operation is complete: it returns immediately. This |
| 255 | means the traces(s) of the recording session might not be valid when |
| 256 | this function returns, and there's no way to know when it/they become |
| 257 | valid. |
| 258 | |
| 259 | @note |
| 260 | An #LTTNG_ACTION_TYPE_STOP_SESSION trigger action can also |
| 261 | deactivate (stop) a recording session. |
| 262 | |
| 263 | @param[in] session_name |
| 264 | Name of the recording session to deactivate/stop. |
| 265 | |
| 266 | @returns |
| 267 | 0 on success, or a \em negative #lttng_error_code enumerator |
| 268 | otherwise. |
| 269 | |
| 270 | @lt_pre_conn |
| 271 | @lt_pre_not_null{session_name} |
| 272 | @lt_pre_sess_exists{session_name} |
| 273 | @lt_pre_sess_active{session_name} |
| 274 | @pre |
| 275 | No deactivation operation is in progress for the recording session |
| 276 | named \lt_p{session_name}. |
| 277 | |
| 278 | @sa lttng_stop_tracing() -- |
| 279 | Deactivates a recording session, blocking until the operation |
| 280 | completes. |
| 281 | @sa lttng_start_tracing() -- |
| 282 | Starts a recording session. |
| 283 | @sa \lt_man{lttng-stop,1} |
| 284 | */ |
| 285 | LTTNG_EXPORT extern int lttng_stop_tracing_no_wait(const char *session_name); |
| 286 | |
| 287 | /* |
| 288 | * Deprecated: As of LTTng 2.9, this function always returns |
| 289 | * -LTTNG_ERR_UND. |
| 290 | */ |
| 291 | #pragma GCC diagnostic push |
| 292 | #pragma GCC diagnostic ignored "-Wshadow" |
| 293 | LTTNG_EXPORT extern int lttng_calibrate(struct lttng_handle *handle, |
| 294 | struct lttng_calibrate *calibrate); |
| 295 | #pragma GCC diagnostic pop |
| 296 | |
| 297 | /* |
| 298 | * Set URL for a consumer for a session and domain. |
| 299 | * |
| 300 | * Both data and control URL must be defined. If both URLs are the same, only |
| 301 | * the control URL is used even for network streaming. |
| 302 | * |
| 303 | * Default port are 5342 and 5343 respectively for control and data which uses |
| 304 | * the TCP protocol. |
| 305 | * |
| 306 | * URL format: proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH] |
| 307 | * |
| 308 | * Possible protocols are: |
| 309 | * > file://... |
| 310 | * Local filesystem full path. |
| 311 | * |
| 312 | * > net[6]://... |
| 313 | * This will use the default network transport layer which is TCP for both |
| 314 | * control (PORT1) and data port (PORT2). |
| 315 | * |
| 316 | * > tcp[6]://... |
| 317 | * TCP only streaming. For this one, both data and control URL must be given. |
| 318 | * |
| 319 | * Return 0 on success else a negative LTTng error code. |
| 320 | */ |
| 321 | LTTNG_EXPORT extern int |
| 322 | lttng_set_consumer_url(struct lttng_handle *handle, const char *control_url, const char *data_url); |
| 323 | |
| 324 | /*! |
| 325 | @brief |
| 326 | Returns whether or not you may read the traces of the recording |
| 327 | session named \lt_p{session_name}. |
| 328 | |
| 329 | @ingroup api_session |
| 330 | |
| 331 | It's not safe to read the traces of a recording session while |
| 332 | LTTng is still consuming data from the tracers for its |
| 333 | \ref api-channel-channel "channels". |
| 334 | |
| 335 | This function makes it possible to know when LTTng is done consuming |
| 336 | trace data from tracers for the channels of the recording session |
| 337 | named \lt_p{session_name}. |
| 338 | |
| 339 | @param[in] session_name |
| 340 | Name of the recording session of which get whether or not |
| 341 | you may read its traces. |
| 342 | |
| 343 | @returns |
| 344 | @parblock |
| 345 | One of: |
| 346 | |
| 347 | <dl> |
| 348 | <dt>0 |
| 349 | <dd> |
| 350 | You may read the traces of the recording session named |
| 351 | \lt_p{session_name}. |
| 352 | |
| 353 | This remains true as long as the recording session remains |
| 354 | \link lttng_session::enabled inactive\endlink (stopped). |
| 355 | |
| 356 | <dt>1</dt> |
| 357 | <dd> |
| 358 | You may \em not read the traces of the recording session named |
| 359 | \lt_p{session_name}. |
| 360 | |
| 361 | <dt>Negative value |
| 362 | <dd> |
| 363 | Error: a negative #lttng_error_code enumerator. |
| 364 | </dl> |
| 365 | @endparblock |
| 366 | |
| 367 | @lt_pre_conn |
| 368 | @lt_pre_not_null{session_name} |
| 369 | @lt_pre_sess_exists{session_name} |
| 370 | @lt_pre_sess_inactive{session_name} |
| 371 | */ |
| 372 | LTTNG_EXPORT extern int lttng_data_pending(const char *session_name); |
| 373 | |
| 374 | /* |
| 375 | * Gets the status of the kernel tracer. |
| 376 | * |
| 377 | * Sets the value of the argument, which must not be null. |
| 378 | */ |
| 379 | LTTNG_EXPORT extern enum lttng_error_code |
| 380 | lttng_get_kernel_tracer_status(enum lttng_kernel_tracer_status *status); |
| 381 | |
| 382 | /*! |
| 383 | @brief |
| 384 | Regenerates the metadata streams of the recording session named |
| 385 | \lt_p{session_name}. |
| 386 | |
| 387 | @ingroup api_session |
| 388 | |
| 389 | @deprecated |
| 390 | Use lttng_regenerate_metadata(). |
| 391 | |
| 392 | @param[in] session_name |
| 393 | Name of the recording session of which to regenerate the metadata |
| 394 | streams. |
| 395 | |
| 396 | @returns |
| 397 | 0 on success, or a \em negative #lttng_error_code enumerator |
| 398 | otherwise. |
| 399 | |
| 400 | @lt_pre_conn |
| 401 | @lt_pre_not_null{session_name} |
| 402 | @lt_pre_sess_exists{session_name} |
| 403 | */ |
| 404 | /// @cond DEPRECATED |
| 405 | LTTNG_DEPRECATED() |
| 406 | /// @endcond |
| 407 | LTTNG_EXPORT extern int lttng_metadata_regenerate(const char *session_name); |
| 408 | |
| 409 | /*! |
| 410 | @brief |
| 411 | Regenerates the metadata streams of the recording session named |
| 412 | \lt_p{session_name}. |
| 413 | |
| 414 | @ingroup api_session |
| 415 | |
| 416 | Use this function to resample the offset between the monotonic clock and |
| 417 | the wall time of the system, and then regenerate (overwrite) all the |
| 418 | metadata stream files (local or remote) of the recording session |
| 419 | named \lt_p{session_name}. |
| 420 | |
| 421 | More specifically, you may want to resample the wall time following a |
| 422 | major <a href="https://en.wikipedia.org/wiki/Network_Time_Protocol">NTP</a> |
| 423 | correction. As such, LTTng can trace a system booting with an incorrect |
| 424 | wall time before its wall time is NTP-corrected. Regenerating the |
| 425 | metadata of a recording session ensures that trace readers |
| 426 | can accurately determine the event record timestamps relative to the |
| 427 | Unix epoch. |
| 428 | |
| 429 | Note that if you plan to \ref api_session_rotation "rotate" the |
| 430 | recording session named \lt_p{session_name}, this function only |
| 431 | regenerates the metadata stream files of the \em current and \em next |
| 432 | trace chunks. |
| 433 | |
| 434 | See the preconditions of this function which show important limitations. |
| 435 | |
| 436 | @param[in] session_name |
| 437 | Name of the recording session of which to regenerate the metadata |
| 438 | streams. |
| 439 | |
| 440 | @returns |
| 441 | 0 on success, or a \em negative #lttng_error_code enumerator |
| 442 | otherwise. |
| 443 | |
| 444 | @lt_pre_conn |
| 445 | @lt_pre_not_null{session_name} |
| 446 | @lt_pre_sess_exists{session_name} |
| 447 | @pre |
| 448 | The recording session named \lt_p{session_name} was \em not created |
| 449 | in \ref api-session-live-mode "live mode". |
| 450 | @pre |
| 451 | All the \ref api-channel-channel "channels" of the recording session |
| 452 | named \lt_p{session_name} use a |
| 453 | \ref api-channel-per-user-buf "per-user buffering scheme". |
| 454 | |
| 455 | @sa lttng_regenerate_statedump() -- |
| 456 | Regenerates the state dump event records of a recording session. |
| 457 | @sa \lt_man{lttng-regenerate,1} |
| 458 | */ |
| 459 | LTTNG_EXPORT extern int lttng_regenerate_metadata(const char *session_name); |
| 460 | |
| 461 | /*! |
| 462 | @brief |
| 463 | Regenerates the state dump event records of the recording session |
| 464 | named \lt_p{session_name}. |
| 465 | |
| 466 | @ingroup api_session |
| 467 | |
| 468 | Use this function to collect up-to-date state dump information and |
| 469 | append corresponding event records to the |
| 470 | \ref api-channel-channel "sub-buffers" of the recording session named |
| 471 | \lt_p{session_name}. |
| 472 | |
| 473 | This is particularly useful if you created the recording session in |
| 474 | \ref api-session-snapshot-mode "snapshot mode" |
| 475 | or if LTTng \ref api_session_rotation "rotates" trace files for one of |
| 476 | its \ref api-channel-channel "channels": in both cases, the state dump |
| 477 | information may be lost. |
| 478 | |
| 479 | @param[in] session_name |
| 480 | Name of the recording session of which to regenerate the |
| 481 | state dump event records. |
| 482 | |
| 483 | @returns |
| 484 | 0 on success, or a \em negative #lttng_error_code enumerator |
| 485 | otherwise. |
| 486 | |
| 487 | @lt_pre_conn |
| 488 | @lt_pre_not_null{session_name} |
| 489 | @lt_pre_sess_exists{session_name} |
| 490 | |
| 491 | @sa lttng_regenerate_metadata() -- |
| 492 | Regenerates the metadata streams of a recording session. |
| 493 | @sa \lt_man{lttng-regenerate,1} |
| 494 | */ |
| 495 | LTTNG_EXPORT extern int lttng_regenerate_statedump(const char *session_name); |
| 496 | |
| 497 | #ifdef __cplusplus |
| 498 | } |
| 499 | #endif |
| 500 | |
| 501 | #endif /* LTTNG_H */ |