include/lttng/session.h

   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}&nbsp;≥&nbsp;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 */