| 1 | /* |
| 2 | * Copyright (C) 2014 David Goulet <dgoulet@efficios.com> |
| 3 | * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com> |
| 4 | * |
| 5 | * SPDX-License-Identifier: LGPL-2.1-only |
| 6 | * |
| 7 | */ |
| 8 | |
| 9 | #ifndef LTTNG_SESSION_H |
| 10 | #define LTTNG_SESSION_H |
| 11 | |
| 12 | #ifdef __cplusplus |
| 13 | extern "C" { |
| 14 | #endif |
| 15 | |
| 16 | #include <lttng/lttng-export.h> |
| 17 | |
| 18 | /*! |
| 19 | @addtogroup api_session |
| 20 | @{ |
| 21 | */ |
| 22 | |
| 23 | #include <lttng/constant.h> |
| 24 | |
| 25 | struct lttng_handle; |
| 26 | struct lttng_session_descriptor; |
| 27 | struct lttng_destruction_handle; |
| 28 | |
| 29 | #define LTTNG_SESSION_PADDING1 8 |
| 30 | |
| 31 | /*! |
| 32 | @brief |
| 33 | Recording session summary. |
| 34 | |
| 35 | The purpose of such a structure is to provide information about a |
| 36 | \lt_obj_session itself, but not about its \lt_obj_domains |
| 37 | and \lt_obj_channels (use lttng_list_domains() and lttng_list_channels() |
| 38 | for this). |
| 39 | |
| 40 | lttng_list_sessions() sets a pointer to an array of all the available |
| 41 | recording session summaries. |
| 42 | */ |
| 43 | struct lttng_session { |
| 44 | /// Name. |
| 45 | char name[LTTNG_NAME_MAX]; |
| 46 | |
| 47 | /*! |
| 48 | @brief |
| 49 | <em>Human-readable</em> representation of the output (local |
| 50 | or remote). |
| 51 | */ |
| 52 | char path[PATH_MAX]; |
| 53 | |
| 54 | /*! |
| 55 | @brief |
| 56 | 1 if this recording session is active (started), or 0 |
| 57 | otherwise. |
| 58 | |
| 59 | @sa lttng_start_tracing() -- |
| 60 | Starts a recording session. |
| 61 | @sa lttng_stop_tracing() -- |
| 62 | Stops a recording session. |
| 63 | */ |
| 64 | uint32_t enabled; /* enabled/started: 1, disabled/stopped: 0 */ |
| 65 | |
| 66 | /*! |
| 67 | @brief |
| 68 | 1 if this recording session was created in |
| 69 | \ref api-session-snapshot-mode "snapshot mode", |
| 70 | or 0 otherwise. |
| 71 | |
| 72 | @note |
| 73 | If this member is 1, then the |
| 74 | lttng_session::live_timer_interval member is 0. |
| 75 | */ |
| 76 | uint32_t snapshot_mode; |
| 77 | |
| 78 | /*! |
| 79 | @brief |
| 80 | Period (µs) of the \ref api-channel-live-timer "live timers" |
| 81 | of the channels of this recording session, or 0 if this |
| 82 | recording session wasn't created in |
| 83 | \ref api-session-live-mode "live mode". |
| 84 | |
| 85 | @note |
| 86 | If this member is \em not 0, then the |
| 87 | lttng_session::snapshot_mode member is 0. |
| 88 | */ |
| 89 | unsigned int live_timer_interval; /* usec */ |
| 90 | |
| 91 | /* |
| 92 | * End of public attributes. |
| 93 | * The remaining fields are used to deal with ABI management concerns. |
| 94 | */ |
| 95 | |
| 96 | /* |
| 97 | * 32-bit architectures are already naturally aligned on 4 bytes after |
| 98 | * 'live_timer_interval'. However, the offset does not result in a |
| 99 | * natural alignment on 64-bit architectures. Adding 4 bytes of |
| 100 | * padding here results in an aligned offset after 'alignement_padding' |
| 101 | * for both bitnesses. |
| 102 | * |
| 103 | * This was added since not all compilers appear to align unions in the |
| 104 | * same way. Some (e.g. MSVC) do not seem to impose an alignement |
| 105 | * constraint while others (e.g. gcc, clang, icc) seem to align it to |
| 106 | * ensure 'ptr' is naturally aligned. |
| 107 | */ |
| 108 | char alignment_padding[4]; |
| 109 | union { |
| 110 | /* |
| 111 | * Ensure the 'extended' union has the same size for both |
| 112 | * 32-bit and 64-bit builds. |
| 113 | */ |
| 114 | char padding[LTTNG_SESSION_PADDING1]; |
| 115 | void *ptr; |
| 116 | } extended; |
| 117 | }; |
| 118 | |
| 119 | /*! |
| 120 | @brief |
| 121 | Creates a recording session from the recording session descriptor |
| 122 | \lt_p{session_descriptor}. |
| 123 | |
| 124 | See \ref api_session_descr to learn how to create a recording session |
| 125 | descriptor. |
| 126 | |
| 127 | On success, if the name property of \lt_p{session_descriptor} isn't set, |
| 128 | this function sets it to the automatically generated name of the |
| 129 | recording session. Get the recording session name with |
| 130 | lttng_session_descriptor_get_session_name(). |
| 131 | |
| 132 | @param[in] session_descriptor |
| 133 | Descriptor from which to create a recording session. |
| 134 | |
| 135 | @returns |
| 136 | #LTTNG_OK on success, or a \em negative enumerator otherwise. |
| 137 | |
| 138 | @lt_pre_conn |
| 139 | @lt_pre_not_null{session_descriptor} |
| 140 | @pre |
| 141 | If the name property of \lt_p{session_descriptor} is set, then no |
| 142 | available recording session has this name. |
| 143 | |
| 144 | @sa \ref api_session_descr. |
| 145 | @sa \lt_man{lttng-create,1} |
| 146 | */ |
| 147 | LTTNG_EXPORT extern enum lttng_error_code |
| 148 | lttng_create_session_ext(struct lttng_session_descriptor *session_descriptor); |
| 149 | |
| 150 | /*! |
| 151 | @brief |
| 152 | Creates a recording session named \lt_p{session_name} in |
| 153 | \ref api-session-local-mode "local" |
| 154 | or \ref api-session-net-mode "network streaming" mode, optionally |
| 155 | setting its output URL to \lt_p{output_url}. |
| 156 | |
| 157 | @deprecated |
| 158 | Use lttng_create_session_ext() with a dedicated |
| 159 | local or network streaming |
| 160 | \ref api_session_descr "recording session descriptor". |
| 161 | |
| 162 | @param[in] session_name |
| 163 | Name of the new recording session. |
| 164 | @param[in] output_url |
| 165 | @parblock |
| 166 | \ref api-session-url "Output URL" of the recording session to |
| 167 | create. |
| 168 | |
| 169 | If it's a \ref api-session-one-port-url "single-port output URL", |
| 170 | then the trace data port is \lt_def_net_data_port. |
| 171 | |
| 172 | If \c NULL, LTTng doesn't write any trace data for this recording |
| 173 | session. |
| 174 | @endparblock |
| 175 | |
| 176 | @returns |
| 177 | 0 on success, or a \em negative #lttng_error_code enumerator |
| 178 | otherwise. |
| 179 | |
| 180 | @lt_pre_conn |
| 181 | @lt_pre_not_null{session_name} |
| 182 | @lt_pre_sess_name_not_auto{session_name} |
| 183 | @pre |
| 184 | No available recording session is named \lt_p{session_name}. |
| 185 | @pre |
| 186 | <strong>If not \c NULL</strong>, \lt_p{output_url} is a valid |
| 187 | \ref api-session-url "output URL". |
| 188 | |
| 189 | @sa lttng_create_session_snapshot() -- |
| 190 | Creates a recording session in snapshot mode. |
| 191 | @sa lttng_create_session_live() -- |
| 192 | Creates a recording session in live mode. |
| 193 | @sa \lt_man{lttng-create,1} |
| 194 | */ |
| 195 | LTTNG_EXPORT extern int lttng_create_session(const char *session_name, const char *output_url); |
| 196 | |
| 197 | /*! |
| 198 | @brief |
| 199 | Creates a recording session named \lt_p{session_name} in |
| 200 | \ref api-session-snapshot-mode "snapshot" mode, optionally setting |
| 201 | the URL of its initial snapshot output to \lt_p{output_url}. |
| 202 | |
| 203 | @deprecated |
| 204 | Use lttng_create_session_ext() with a dedicated snapshot |
| 205 | \ref api_session_descr "recording session descriptor". |
| 206 | |
| 207 | @param[in] session_name |
| 208 | Name of the new recording session. |
| 209 | @param[in] output_url |
| 210 | @parblock |
| 211 | \ref api-session-url "URL" of an initial snapshot output |
| 212 | which LTTng adds to this recording session. |
| 213 | |
| 214 | If it's a \ref api-session-one-port-url "single-port output URL", |
| 215 | then the trace data port is \lt_def_net_data_port. |
| 216 | |
| 217 | This initial snapshot output is named <code>snapshot-0</code>. |
| 218 | |
| 219 | If \c NULL, then the created recording session has no initial |
| 220 | snapshot output: you need to either add one with |
| 221 | lttng_snapshot_add_output() or provide one when you take a snapshot |
| 222 | with lttng_snapshot_record(). |
| 223 | @endparblock |
| 224 | |
| 225 | @returns |
| 226 | 0 on success, or a \em negative #lttng_error_code enumerator |
| 227 | otherwise. |
| 228 | |
| 229 | @lt_pre_conn |
| 230 | @lt_pre_not_null{session_name} |
| 231 | @lt_pre_sess_name_not_auto{session_name} |
| 232 | @pre |
| 233 | No available recording session is named \lt_p{session_name}. |
| 234 | @pre |
| 235 | <strong>If not \c NULL</strong>, \lt_p{output_url} is a valid |
| 236 | \ref api-session-url "output URL". |
| 237 | |
| 238 | @sa lttng_create_session() -- |
| 239 | Creates a recording session in local or network streaming mode. |
| 240 | @sa lttng_create_session_live() -- |
| 241 | Creates a recording session in live mode. |
| 242 | @sa \lt_man{lttng-create,1} |
| 243 | */ |
| 244 | LTTNG_EXPORT extern int lttng_create_session_snapshot(const char *session_name, |
| 245 | const char *output_url); |
| 246 | |
| 247 | /*! |
| 248 | @brief |
| 249 | Creates a recording session named \lt_p{session_name} in |
| 250 | \ref api-session-live-mode "live" mode, optionally setting its |
| 251 | URL to \lt_p{output_url}. |
| 252 | |
| 253 | @deprecated |
| 254 | Use lttng_create_session_ext() with a dedicated live |
| 255 | \ref api_session_descr "recording session descriptor". |
| 256 | |
| 257 | @param[in] session_name |
| 258 | Name of the new recording session. |
| 259 | @param[in] output_url |
| 260 | @parblock |
| 261 | \ref api-session-url "Output URL" of the recording session to |
| 262 | create: \ref api-session-one-port-url "single-port" or |
| 263 | \ref api-session-two-port-url "two-port". |
| 264 | |
| 265 | If it's a \ref api-session-one-port-url "single-port output URL", |
| 266 | then the trace data port is \lt_def_net_data_port. |
| 267 | |
| 268 | If \c NULL, this function uses \lt_def_net_url. |
| 269 | @endparblock |
| 270 | @param[in] live_timer_period |
| 271 | Period (µs) of the \ref api-channel-live-timer "live timers" of all |
| 272 | the channels of the created recording session. |
| 273 | |
| 274 | @returns |
| 275 | 0 on success, or a \em negative #lttng_error_code enumerator |
| 276 | otherwise. |
| 277 | |
| 278 | @lt_pre_conn |
| 279 | @lt_pre_not_null{session_name} |
| 280 | @lt_pre_sess_name_not_auto{session_name} |
| 281 | @pre |
| 282 | No available recording session is named \lt_p{session_name}. |
| 283 | @pre |
| 284 | <strong>If not \c NULL</strong>, \lt_p{output_url} is a valid |
| 285 | \ref api-session-one-port-url "single-port output URL" or |
| 286 | \ref api-session-two-port-url "two-port output URL". |
| 287 | @pre |
| 288 | \lt_p{live_timer_period} ≥ 1 |
| 289 | |
| 290 | @sa lttng_create_session() -- |
| 291 | Creates a recording session in local or network streaming mode. |
| 292 | @sa lttng_create_session_snapshot() -- |
| 293 | Creates a recording session in snapshot mode. |
| 294 | @sa \lt_man{lttng-create,1} |
| 295 | */ |
| 296 | LTTNG_EXPORT extern int lttng_create_session_live(const char *session_name, |
| 297 | const char *output_url, |
| 298 | unsigned int live_timer_period); |
| 299 | |
| 300 | /*! |
| 301 | @brief |
| 302 | Destroys the recording session named \lt_p{session_name}, blocking |
| 303 | until the operation completes. |
| 304 | |
| 305 | @deprecated |
| 306 | Use lttng_destroy_session_ext(). |
| 307 | |
| 308 | "Destroying" a recording session means freeing the resources which the |
| 309 | LTTng daemons and tracers acquired for it, also making sure to flush all |
| 310 | the recorded trace data to either the local file system or the connected |
| 311 | LTTng relay daemon (see \lt_man{lttng-relayd,8}), depending on the |
| 312 | \ref api-session-modes "recording session mode". |
| 313 | |
| 314 | This function stops any recording activity within the recording session |
| 315 | named \lt_p{session_name}. |
| 316 | |
| 317 | This function implicitly calls lttng_stop_tracing(), blocking until the |
| 318 | trace data of the recording session becomes valid. Use |
| 319 | lttng_destroy_session_no_wait() to avoid a blocking call. |
| 320 | |
| 321 | @param[in] session_name |
| 322 | Name of the recording session to destroy. |
| 323 | |
| 324 | @returns |
| 325 | 0 on success, or a \em negative #lttng_error_code enumerator |
| 326 | otherwise. |
| 327 | |
| 328 | @lt_pre_conn |
| 329 | @lt_pre_not_null{session_name} |
| 330 | @lt_pre_sess_exists{session_name} |
| 331 | |
| 332 | @sa lttng_destroy_session_no_wait() -- |
| 333 | Initiates the destruction operation of a recording session, |
| 334 | returning immediately. |
| 335 | @sa \lt_man{lttng-destroy,1} |
| 336 | */ |
| 337 | LTTNG_EXPORT extern int lttng_destroy_session(const char *session_name); |
| 338 | |
| 339 | /*! |
| 340 | @brief |
| 341 | Initiates the destruction operation of the recording session named |
| 342 | \lt_p{session_name}. |
| 343 | |
| 344 | @deprecated |
| 345 | Use lttng_destroy_session_ext(). |
| 346 | |
| 347 | "Destroying" a recording session means freeing the resources which the |
| 348 | LTTng daemons and tracers acquired for it, also making sure to flush all |
| 349 | the recorded trace data to either the local file system or the connected |
| 350 | LTTng relay daemon (see \lt_man{lttng-relayd,8}), depending on the |
| 351 | \ref api-session-modes "recording session mode". |
| 352 | |
| 353 | Unlike lttng_destroy_session(), this function does \em not block until |
| 354 | the destruction operation is complete: it returns immediately. This |
| 355 | means the trace(s) of the recording session might not be valid when |
| 356 | this function returns, and there's no way to know when it/they become |
| 357 | valid. |
| 358 | |
| 359 | @param[in] session_name |
| 360 | Name of the recording session to destroy. |
| 361 | |
| 362 | @returns |
| 363 | 0 on success, or a \em negative #lttng_error_code enumerator |
| 364 | otherwise. |
| 365 | |
| 366 | @lt_pre_conn |
| 367 | @lt_pre_not_null{session_name} |
| 368 | @lt_pre_sess_exists{session_name} |
| 369 | @pre |
| 370 | No destruction operation is in progress for the recording session |
| 371 | named \lt_p{session_name}. |
| 372 | |
| 373 | @sa lttng_destroy_session() -- |
| 374 | Destroys a recording session, blocking until the operation |
| 375 | completes. |
| 376 | @sa \lt_man{lttng-destroy,1} |
| 377 | */ |
| 378 | LTTNG_EXPORT extern int lttng_destroy_session_no_wait(const char *session_name); |
| 379 | |
| 380 | /*! |
| 381 | @brief |
| 382 | Initiates a destruction operation of the recording session |
| 383 | named \lt_p{session_name}. |
| 384 | |
| 385 | "Destroying" a recording session means freeing the resources which the |
| 386 | LTTng daemons and tracers acquired for it, also making sure to flush all |
| 387 | the recorded trace data to either the local file system or the connected |
| 388 | LTTng relay daemon (see \lt_man{lttng-relayd,8}), depending on the |
| 389 | \ref api-session-modes "recording session mode". |
| 390 | |
| 391 | This function doesn't block until the destruction operation completes: |
| 392 | it only initiates the operation. |
| 393 | Use \lt_p{*handle} to wait for the operation to complete. |
| 394 | |
| 395 | @param[in] session_name |
| 396 | Name of the recording session to destroy. |
| 397 | @param[out] handle |
| 398 | @parblock |
| 399 | <strong>On success</strong>, this function sets \lt_p{*handle} to |
| 400 | a handle which identifies this recording session destruction |
| 401 | operation. |
| 402 | |
| 403 | May be \c NULL. |
| 404 | |
| 405 | Wait for the completion of this destruction operation with |
| 406 | lttng_destruction_handle_wait_for_completion(). |
| 407 | |
| 408 | Destroy \lt_p{*handle} with lttng_destruction_handle_destroy(). |
| 409 | @endparblock |
| 410 | |
| 411 | @returns |
| 412 | #LTTNG_OK on success, or a \em negative enumerator otherwise. |
| 413 | |
| 414 | @lt_pre_conn |
| 415 | @lt_pre_not_null{session_name} |
| 416 | @lt_pre_sess_exists{session_name} |
| 417 | @pre |
| 418 | No destruction operation is in progress for the recording session |
| 419 | named \lt_p{session_name}. |
| 420 | |
| 421 | @sa \lt_man{lttng-destroy,1} |
| 422 | */ |
| 423 | LTTNG_EXPORT extern enum lttng_error_code |
| 424 | lttng_destroy_session_ext(const char *session_name, struct lttng_destruction_handle **handle); |
| 425 | |
| 426 | /*! |
| 427 | @brief |
| 428 | Sets \lt_p{*sessions} to the summaries of all the available |
| 429 | recording sessions. |
| 430 | |
| 431 | @param[out] sessions |
| 432 | @parblock |
| 433 | <strong>On success</strong>, this function sets \lt_p{*sessions} to |
| 434 | the summaries of the available recording sessions. |
| 435 | |
| 436 | Free \lt_p{*sessions} with <code>free()</code>. |
| 437 | @endparblock |
| 438 | |
| 439 | @returns |
| 440 | The number of items in \lt_p{*sessions} on success, or a \em |
| 441 | negative #lttng_error_code enumerator otherwise. |
| 442 | |
| 443 | @lt_pre_conn |
| 444 | @lt_pre_not_null{sessions} |
| 445 | |
| 446 | @sa \lt_man{lttng-list,1} |
| 447 | */ |
| 448 | LTTNG_EXPORT extern int lttng_list_sessions(struct lttng_session **sessions); |
| 449 | |
| 450 | /*! |
| 451 | @brief |
| 452 | Sets \lt_p{*creation_timestamp} to the timestamp of the creation of |
| 453 | the recording session summarized by \lt_p{session}. |
| 454 | |
| 455 | @param[in] session |
| 456 | Summary of the recording session of which to get the creation |
| 457 | timestamp, as obtained with lttng_list_sessions(). |
| 458 | @param[out] creation_timestamp |
| 459 | <strong>On success</strong>, this function sets |
| 460 | \lt_p{*creation_timestamp} to the Unix timestamp of the creation of |
| 461 | \lt_p{session}. |
| 462 | |
| 463 | @returns |
| 464 | #LTTNG_OK on success, or a \em negative enumerator otherwise. |
| 465 | |
| 466 | @lt_pre_conn |
| 467 | @lt_pre_not_null{session} |
| 468 | @pre |
| 469 | The recording session summarized by \lt_p{session} is accessible |
| 470 | within the connected session daemon. |
| 471 | @lt_pre_not_null{creation_timestamp} |
| 472 | */ |
| 473 | LTTNG_EXPORT extern enum lttng_error_code |
| 474 | lttng_session_get_creation_time(const struct lttng_session *session, uint64_t *creation_timestamp); |
| 475 | |
| 476 | /*! |
| 477 | @brief |
| 478 | Sets the path of the directory containing the shared memory files |
| 479 | holding the channel ring buffers of the recording session named |
| 480 | \lt_p{session_name} on the local file sytem to \lt_p{shm_dir}. |
| 481 | |
| 482 | Specifying a location on an |
| 483 | <a href="https://en.wikipedia.org/wiki/Non-volatile_random-access_memory">NVRAM</a> |
| 484 | file system makes it possible to recover the latest recorded trace data |
| 485 | when the system reboots after a crash with the \lt_man{lttng-crash,1} |
| 486 | utility. |
| 487 | |
| 488 | @param[in] session_name |
| 489 | Name of the recording session of which to set the shared memory |
| 490 | file directory path. |
| 491 | @param[in] shm_dir |
| 492 | Path of the directory containing the shared memory files of the |
| 493 | recording session named \lt_p{session_name}. |
| 494 | |
| 495 | @returns |
| 496 | 0 on success, or a \em negative #lttng_error_code enumerator |
| 497 | otherwise. |
| 498 | |
| 499 | @lt_pre_conn |
| 500 | @lt_pre_not_null{session_name} |
| 501 | @lt_pre_sess_exists{session_name} |
| 502 | @lt_pre_sess_never_active{session_name} |
| 503 | @lt_pre_not_null{shm_dir} |
| 504 | @pre |
| 505 | \lt_p{shm_dir} is a writable directory. |
| 506 | */ |
| 507 | LTTNG_EXPORT extern int lttng_set_session_shm_path(const char *session_name, const char *shm_dir); |
| 508 | |
| 509 | /// @} |
| 510 | |
| 511 | #ifdef __cplusplus |
| 512 | } |
| 513 | #endif |
| 514 | |
| 515 | #endif /* LTTNG_SESSION_H */ |