include/lttng/channel.h

   1 /*
   2  * Copyright (C) 2014 David Goulet <dgoulet@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_CHANNEL_H
   9 #define LTTNG_CHANNEL_H
  10
  11 #include <lttng/domain.h>
  12 #include <lttng/event.h>
  13 #include <lttng/lttng-export.h>
  14
  15 #include <stdint.h>
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif
  20
  21 /*
  22  * Tracer channel attributes. For both kernel and user-space.
  23  *
  24  * The structures should be initialized to zero before use.
  25  */
  26 #define LTTNG_CHANNEL_ATTR_PADDING1 LTTNG_SYMBOL_NAME_LEN + 12
  27
  28 /*!
  29 @brief
  30     Attributes of a \link #lttng_channel channel summary\endlink.
  31
  32 @ingroup api_channel
  33
  34 The lttng_channel::attr member is an instance of such a structure.
  35
  36 lttng_channel_set_default_attr() sets the members of such a structure
  37 to their default values given a specific \lt_obj_domain summary.
  38
  39 \anchor api-channel-valid-attr-struct A \em valid #lttng_channel_attr
  40 structure satisfies the following constraints:
  41
  42 <table>
  43   <tr>
  44     <th>Member
  45     <th>Constraints
  46   <tr>
  47     <td>lttng_channel_attr::overwrite
  48     <td>0, 1, or -1
  49   <tr>
  50     <td>lttng_channel_attr::subbuf_size
  51     <td>
  52       - Greater than 0
  53       - Power of two
  54   <tr>
  55     <td>lttng_channel_attr::num_subbuf
  56     <td>
  57       - Greater than 0
  58       - Power of two
  59 </table>
  60 */
  61 struct lttng_channel_attr {
  62         /*!
  63         @brief
  64             \ref api-channel-er-loss-mode "Event record loss mode".
  65
  66         One of:
  67
  68         <dl>
  69           <dt>0
  70           <dd>
  71             The \ref api-channel-er-loss-mode "event record loss mode"
  72             of the channel is
  73             <em>\ref api-channel-discard-mode "discard"</em>.
  74
  75           <dt>1
  76           <dd>
  77             The event record loss mode of the channel is
  78             <em>\ref api-channel-overwrite-mode "overwrite"</em>.
  79
  80           <dt>-1
  81           <dd>
  82             The event record loss mode of the channel is the default
  83             value of its \lt_obj_session:
  84
  85             <dl>
  86               <dt>\ref api-session-snapshot-mode "Snapshot mode"
  87               <dd>Overwrite mode
  88
  89               <dt>Other modes
  90               <dd>Discard mode
  91             </dl>
  92         </dl>
  93         */
  94         int overwrite; /* -1: session default, 1: overwrite, 0: discard */
  95
  96         /*!
  97         @brief
  98             \ref api-channel-sub-buf-size-count "Sub-buffer size"
  99             (bytes).
 100         */
 101         uint64_t subbuf_size; /* bytes, power of 2 */
 102
 103         /*!
 104         @brief
 105             \ref api-channel-sub-buf-size-count "Sub-buffer count".
 106         */
 107         uint64_t num_subbuf; /* power of 2 */
 108
 109         /*!
 110         @brief
 111             \ref api-channel-switch-timer "Switch timer period" (µs),
 112             if applicable.
 113
 114         Only available if the \lt_obj_session which
 115         owns this channel is \em not in
 116         \ref api-session-live-mode "live mode".
 117         */
 118         unsigned int switch_timer_interval; /* usec */
 119
 120         /// \ref api-channel-read-timer "Read timer period" (µs).
 121         unsigned int read_timer_interval; /* usec */
 122
 123         /// Output type (Linux kernel channel).
 124         enum lttng_event_output output; /* splice, mmap */
 125
 126         /* LTTng 2.1 padding limit */
 127
 128         /*!
 129         @brief
 130             \ref api-channel-max-trace-file-size-count "Maximum trace file size"
 131             (bytes), or 0 for unlimited.
 132         */
 133         uint64_t tracefile_size; /* bytes */
 134
 135         /*!
 136         @brief
 137             \ref api-channel-max-trace-file-size-count "Maximum trace file count",
 138             or 0 for unlimited.
 139         */
 140         uint64_t tracefile_count; /* number of tracefiles */
 141
 142         /* LTTng 2.3 padding limit */
 143
 144         /*!
 145         @brief
 146             \ref api-channel-live-timer "Live timer period" (µs), if
 147             applicable.
 148
 149         You may \em not set this member: use the
 150         \lt_p{live_timer_period} parameter of
 151         lttng_session_descriptor_live_network_create() when you create
 152         the descriptor of a \ref api-session-live-mode "live" recording
 153         session to contain the channel to create.
 154
 155         Only available if the \lt_obj_session which
 156         owns this channel is in \ref api-session-live-mode "live mode".
 157         */
 158         unsigned int live_timer_interval; /* usec */
 159
 160         /* LTTng 2.7 padding limit */
 161         uint32_t align_to_64;
 162         union {
 163                 uint64_t padding;
 164                 void *ptr;
 165         } extended;
 166
 167         char padding[LTTNG_CHANNEL_ATTR_PADDING1];
 168 };
 169
 170 /*
 171  * Channel information structure. For both kernel and user-space.
 172  *
 173  * The structures should be initialized to zero before use.
 174  */
 175 #define LTTNG_CHANNEL_PADDING1 16
 176
 177 /*!
 178 @brief
 179     \lt_obj_c_channel summary.
 180
 181 @ingroup api_channel
 182
 183 The purpose of such a structure is to provide information about a
 184 channel itself, but not about its \lt_obj_rers
 185 (use lttng_list_events() for this).
 186
 187 lttng_list_channels() sets a pointer to an array of all the
 188 channel summaries of a given \lt_obj_session and \lt_obj_domain.
 189
 190 Most properties are part of the lttng_channel::attr member, but the
 191 following ones have their own dedicated accessors:
 192
 193 <dl>
 194   <dt>\ref api-channel-monitor-timer "Monitor timer" period
 195   <dd>
 196     - lttng_channel_get_monitor_timer_interval()
 197     - lttng_channel_set_monitor_timer_interval()
 198
 199   <dt>\ref api-channel-blocking-timeout "Blocking timeout"
 200   <dd>
 201     - lttng_channel_get_blocking_timeout()
 202     - lttng_channel_set_blocking_timeout()
 203 </dl>
 204
 205 Create a channel summary with lttng_channel_create().
 206
 207 Destroy a channel summary with lttng_channel_destroy().
 208 */
 209 struct lttng_channel {
 210         /// Name.
 211         char name[LTTNG_SYMBOL_NAME_LEN];
 212
 213         /*!
 214         @brief
 215             1 if this \lt_obj_channel is enabled, or 0 otherwise.
 216
 217         @sa lttng_enable_channel() --
 218             Creates or enables a channel.
 219         @sa lttng_disable_channel() --
 220             Disables a channel.
 221         */
 222         uint32_t enabled;
 223
 224         /// Other properties.
 225         struct lttng_channel_attr attr;
 226
 227         char padding[LTTNG_CHANNEL_PADDING1];
 228 };
 229
 230 /*!
 231 @brief
 232     Creates and returns a \lt_obj_channel summary,
 233     setting the members of its lttng_channel::attr member to default
 234     values according to the \lt_obj_domain summary \lt_p{domain}.
 235
 236 @ingroup api_channel
 237
 238 This function internally calls
 239
 240 @code
 241 lttng_channel_set_default_attr(domain, &channel->attr);
 242 @endcode
 243
 244 where \c channel is the returned channel summary.
 245
 246 After you create a channel summary with this function, you can modify
 247 its \ref api-channel-channel-props "properties" and call
 248 lttng_enable_channel() to create and enable a channel.
 249
 250 @param[in] domain
 251     Tracing domain summary to consider to set the members of the
 252     lttng_channel::attr member of the returned structure to default
 253     values.
 254
 255 @returns
 256     @parblock
 257     New channel summary.
 258
 259     Destroy the returned channel summary with lttng_channel_destroy().
 260     @endparblock
 261
 262 @lt_pre_not_null{domain}
 263
 264 @sa lttng_channel_destroy() --
 265     Destroys a channel summary.
 266 */
 267 LTTNG_EXPORT extern struct lttng_channel *lttng_channel_create(struct lttng_domain *domain);
 268
 269 /*!
 270 @brief
 271     Destroys the \lt_obj_channel summary \lt_p{channel}.
 272
 273 @ingroup api_channel
 274
 275 @note
 276     This function doesn't destroy the \lt_obj_channel
 277     which \lt_p{channel} summarizes: the only way to destroy a channel
 278     is to \link lttng_destroy_session_ext() destroy its recording
 279     session\endlink.
 280
 281 @param[in] channel
 282     @parblock
 283     Channel summary to destroy.
 284
 285     May be \c NULL.
 286     @endparblock
 287 */
 288 LTTNG_EXPORT extern void lttng_channel_destroy(struct lttng_channel *channel);
 289
 290 /*!
 291 @brief
 292     Sets \lt_p{*channels} to the summaries of the
 293     \lt_obj_channels of the recording session handle \lt_p{handle}.
 294
 295 @ingroup api_session
 296
 297 @param[in] handle
 298     Recording session handle which contains the name of the recording
 299     session and the summary of the \lt_obj_domain which own the channels
 300     of which to get the summaries.
 301 @param[out] channels
 302     @parblock
 303     <strong>On success</strong>, this function sets \lt_p{*channels} to
 304     the summaries of the channels.
 305
 306     Free \lt_p{*channels} with <code>free()</code>.
 307     @endparblock
 308
 309 @returns
 310     The number of items in \lt_p{*channels} on success, or a \em
 311     negative #lttng_error_code enumerator otherwise.
 312
 313 @lt_pre_conn
 314 @lt_pre_not_null{handle}
 315 @lt_pre_valid_c_str{handle->session_name}
 316 @lt_pre_sess_exists{handle->session_name}
 317 @pre
 318     \lt_p{handle->domain} is valid as per the documentation of
 319     #lttng_domain.
 320 @lt_pre_not_null{channels}
 321 */
 322 LTTNG_EXPORT extern int lttng_list_channels(struct lttng_handle *handle,
 323                                             struct lttng_channel **channels);
 324
 325 /*!
 326 @brief
 327     Creates or enables a \lt_obj_channel summarized by \lt_p{channel}
 328     within the recording session handle \lt_p{handle}.
 329
 330 @ingroup api_channel
 331
 332 This function, depending on \lt_p{channel->name}:
 333
 334 <dl>
 335   <dt>
 336     \lt_p{channel-&gt;name} names an existing
 337     channel within the \lt_obj_session and
 338     \lt_obj_domain of \lt_p{handle}
 339   <dd>
 340     Enables the existing channel.
 341
 342     In this case, this function only uses \lt_p{channel->name}, ignoring
 343     all the other properties of \lt_p{channel}.
 344
 345   <dt>Otherwise
 346   <dd>
 347     Creates and enables a new channel, considering all the properties of
 348     \lt_p{channel}.
 349 </dl>
 350
 351 @param[in] handle
 352     Recording session handle which contains the name of the
 353     recording session and the summary of the \lt_obj_domain which own
 354     the channel to create or enable.
 355 @param[in] channel
 356     Summary of the channel to create or enable.
 357
 358 @returns
 359     0 on success, or a \em negative #lttng_error_code enumerator
 360     otherwise.
 361
 362 @lt_pre_conn
 363 @lt_pre_not_null{handle}
 364 @lt_pre_valid_c_str{handle->session_name}
 365 @lt_pre_sess_exists{handle->session_name}
 366 @pre
 367     \lt_p{handle->domain} is valid as per the documentation of
 368     #lttng_domain.
 369 @lt_pre_not_null{channel}
 370 @pre
 371     <strong>If this function must create a new channel</strong>, then
 372     \lt_p{channel->attr} is \ref api-channel-valid-attr-struct "valid".
 373 @pre
 374     <strong>If this function must create a new channel</strong>, then
 375     \lt_p{handle->session_name} names a
 376     \lt_obj_session which never became
 377     \link lttng_session::enabled active\endlink (started) since its
 378     creation.
 379 @pre
 380     <strong>If this function must create a new channel</strong>, then
 381     all the existing channels of \lt_p{handle} have the same
 382     \ref api-channel-buf-scheme "buffering scheme".
 383
 384 @sa lttng_disable_channel() --
 385     Disables a channel.
 386 */
 387 LTTNG_EXPORT extern int lttng_enable_channel(struct lttng_handle *handle,
 388                                              struct lttng_channel *channel);
 389
 390 /*!
 391 @brief
 392     Disables the \lt_obj_channel named \lt_p{channel_name} within the
 393     recording session handle \lt_p{handle}.
 394
 395 @ingroup api_channel
 396
 397 @param[in] handle
 398     Recording session handle which contains the name of the
 399     recording session and the summary of the \lt_obj_domain which own
 400     the channel to disable.
 401 @param[in] channel_name
 402     Name of the channel to disable within \lt_p{handle}.
 403
 404 @returns
 405     0 on success, or a \em negative #lttng_error_code enumerator
 406     otherwise.
 407
 408 @lt_pre_conn
 409 @lt_pre_not_null{handle}
 410 @lt_pre_valid_c_str{handle->session_name}
 411 @lt_pre_sess_exists{handle->session_name}
 412 @pre
 413     \lt_p{handle->domain} is valid as per the documentation of
 414     #lttng_domain.
 415 @lt_pre_not_null{channel_name}
 416 @pre
 417     \lt_p{channel_name} names an existing channel within the recording
 418     session and tracing domain of \lt_p{handle}.
 419
 420 @sa lttng_enable_channel() --
 421     Creates or enables a channel.
 422 */
 423 LTTNG_EXPORT extern int lttng_disable_channel(struct lttng_handle *handle,
 424                                               const char *channel_name);
 425
 426 /*!
 427 @brief
 428     Sets the members of \lt_p{attr} to their default values considering
 429     the \lt_obj_domain summary \lt_p{domain}.
 430
 431 @ingroup api_channel
 432
 433 Use this function on an lttng_channel::attr member.
 434
 435 @param[in] domain
 436     Tracing domain summary to consider to set the members of \lt_p{attr}
 437     to their default values.
 438 @param[in] attr
 439     Structure of which to set the members to their default values.
 440
 441 @lt_pre_not_null{domain}
 442 @lt_pre_not_null{attr}
 443 */
 444 LTTNG_EXPORT extern void lttng_channel_set_default_attr(struct lttng_domain *domain,
 445                                                         struct lttng_channel_attr *attr);
 446
 447 /*!
 448 @brief
 449     Sets \lt_p{*count} to the number of discarded event
 450     records of the \lt_obj_channel summarized by \lt_p{channel}.
 451
 452 @ingroup api_channel
 453
 454 In \ref api-channel-discard-mode "discard mode", LTTng discards an event
 455 record when there's no sub-buffer left to write it.
 456
 457 lttng_list_channels() sets a pointer to an array of all the
 458 channel summaries of a given \lt_obj_session and \lt_obj_domain.
 459
 460 @param[in] channel
 461     Summary of the channel of which to get the number of discarded
 462     event records.
 463 @param[out] count
 464     <strong>On success</strong>, this function sets \lt_p{*count} to
 465     the number of discarded event records of the channel summarized
 466     by \lt_p{channel}.
 467
 468 @returns
 469     0 on success, or a \em negative #lttng_error_code enumerator
 470     otherwise.
 471
 472 @lt_pre_not_null{channel}
 473 @pre
 474     You obtained \lt_p{channel} with lttng_list_channels().
 475 @pre
 476     The lttng_channel_attr::overwrite member of \lt_p{channel->attr}
 477     is 0.
 478 @lt_pre_not_null{count}
 479
 480 @sa lttng_channel_get_lost_packet_count() --
 481     Returns the number of discarded packets (sub-buffers) of a channel.
 482 */
 483 LTTNG_EXPORT extern int lttng_channel_get_discarded_event_count(struct lttng_channel *channel,
 484                                                                 uint64_t *count);
 485
 486 /*!
 487 @brief
 488     Sets \lt_p{*count} to the number of discarded packets (sub-buffers)
 489     of the \lt_obj_channel summarized by \lt_p{channel}.
 490
 491 @ingroup api_channel
 492
 493 In \ref api-channel-overwrite-mode "overwrite mode", LTTng discards a
 494 whole sub-buffer when there's no sub-buffer left to record an event.
 495
 496 lttng_list_channels() sets a pointer to an array of all the
 497 channel summaries of a given \lt_obj_session and \lt_obj_domain.
 498
 499 @param[in] channel
 500     Summary of the channel of which to get the number of discarded
 501     packets.
 502 @param[out] count
 503     <strong>On success</strong>, this function sets \lt_p{*count} to
 504     the number of discarded packets of the channel summarized
 505     by \lt_p{channel}.
 506
 507 @returns
 508     0 on success, or a \em negative #lttng_error_code enumerator
 509     otherwise.
 510
 511 @lt_pre_not_null{channel}
 512 @pre
 513     You obtained \lt_p{channel} with lttng_list_channels().
 514 @pre
 515     The lttng_channel_attr::overwrite member of \lt_p{channel->attr}
 516     is 1.
 517 @lt_pre_not_null{count}
 518
 519 @sa lttng_channel_get_discarded_event_count() --
 520     Returns the number of discarded event records of a channel.
 521 */
 522 LTTNG_EXPORT extern int lttng_channel_get_lost_packet_count(struct lttng_channel *channel,
 523                                                             uint64_t *count);
 524
 525 /*!
 526 @brief
 527     Sets \lt_p{period} to the
 528     \ref api-channel-monitor-timer "monitor timer" period (µs)
 529     property of the \lt_obj_channel summary \lt_p{channel}.
 530
 531 @ingroup api_channel
 532
 533 @param[in] channel
 534     Summary of the channel of which to get the monitor timer period.
 535 @param[out] period
 536     <strong>On success</strong>, this function sets \lt_p{*period} to
 537     the monitor timer period (µs) property of \lt_p{channel}.
 538
 539 @returns
 540     0 on success, or a \em negative #lttng_error_code enumerator
 541     otherwise.
 542
 543 @lt_pre_not_null{channel}
 544 @lt_pre_not_null{period}
 545
 546 @sa lttng_channel_set_monitor_timer_interval() --
 547     Sets the monitor timer period property of a channel summary.
 548 */
 549 LTTNG_EXPORT extern int lttng_channel_get_monitor_timer_interval(struct lttng_channel *channel,
 550                                                                  uint64_t *period);
 551
 552 /*!
 553 @brief
 554     Sets the \ref api-channel-monitor-timer "monitor timer" period
 555     property of the channel summary \lt_p{channel} to
 556     \lt_p{period}&nbsp;µs.
 557
 558 @ingroup api_channel
 559
 560 @param[in] channel
 561     Channel summary of which to set the monitor timer period
 562     to \lt_p{period}&nbsp;µs.
 563 @param[in] period
 564     Monitor timer period property to set.
 565
 566 @returns
 567     0 on success, or a \em negative #lttng_error_code enumerator
 568     otherwise.
 569
 570 @lt_pre_not_null{channel}
 571 @pre
 572     \lt_p{period}&nbsp;≥&nbsp;1
 573
 574 @sa lttng_channel_get_monitor_timer_interval() --
 575     Returns the monitor timer period property of a channel summary.
 576 */
 577 LTTNG_EXPORT extern int lttng_channel_set_monitor_timer_interval(struct lttng_channel *channel,
 578                                                                  uint64_t period);
 579
 580 /*!
 581 @brief
 582     Sets \lt_p{timeout} to the
 583     \ref api-channel-blocking-timeout "blocking timeout"
 584     property of the \lt_obj_channel summary \lt_p{channel}.
 585
 586 @ingroup api_channel
 587
 588 This property only applies to \link #LTTNG_DOMAIN_UST user space\endlink
 589 channels.
 590
 591 @param[in] channel
 592     Summary of the channel of which to get the blocking timeout.
 593 @param[out] timeout
 594     @parblock
 595     <strong>On success</strong>, this function sets \lt_p{*timeout} to
 596     one of:
 597
 598     <dl>
 599       <dt>-1
 600       <dd>
 601         The blocking timeout of \lt_p{channel} is infinite.
 602
 603       <dt>0
 604       <dd>
 605         Blocking is disabled for \lt_p{channel}.
 606
 607       <dt>Otherwise
 608       <dd>
 609         The blocking timeout of \lt_p{channel} is
 610         \lt_p{*timeout}&nbsp;µs.
 611     </dl>
 612     @endparblock
 613
 614 @returns
 615     0 on success, or a \em negative #lttng_error_code enumerator
 616     otherwise.
 617
 618 @lt_pre_not_null{channel}
 619 @pre
 620     The \lt_obj_domain type of \lt_p{channel} is #LTTNG_DOMAIN_UST.
 621 @lt_pre_not_null{timeout}
 622
 623 @sa lttng_channel_set_blocking_timeout() --
 624     Sets the blocking timeout property of a channel summary.
 625 */
 626 LTTNG_EXPORT extern int lttng_channel_get_blocking_timeout(struct lttng_channel *channel,
 627                                                            int64_t *timeout);
 628
 629 /*!
 630 @brief
 631     Sets the \ref api-channel-blocking-timeout "blocking timeout"
 632     property of the channel summary \lt_p{channel} to
 633     \lt_p{timeout}.
 634
 635 @ingroup api_channel
 636
 637 This property only applies to \link #LTTNG_DOMAIN_UST user space\endlink
 638 channels.
 639
 640 @param[in] channel
 641     Channel summary of which to set the blocking timeout
 642     to \lt_p{timeout}.
 643 @param[in] timeout
 644     @parblock
 645     One of:
 646
 647     <dl>
 648       <dt>-1
 649       <dd>
 650         The blocking timeout of \lt_p{channel} is infinite.
 651
 652       <dt>0
 653       <dd>
 654         Blocking is disabled for \lt_p{channel}.
 655
 656       <dt>Otherwise
 657       <dd>
 658         The blocking timeout of \lt_p{channel} is
 659         \lt_p{timeout}&nbsp;µs.
 660     </dl>
 661     @endparblock
 662
 663 @returns
 664     0 on success, or a \em negative #lttng_error_code enumerator
 665     otherwise.
 666
 667 @lt_pre_not_null{channel}
 668 @pre
 669     The \lt_obj_domain type of \lt_p{channel} is #LTTNG_DOMAIN_UST.
 670 @pre
 671     \lt_p{timeout}&nbsp;≥&nbsp;-1
 672
 673 @sa lttng_channel_get_blocking_timeout() --
 674     Returns the blocking timeout property of a channel summary.
 675 */
 676 LTTNG_EXPORT extern int lttng_channel_set_blocking_timeout(struct lttng_channel *channel,
 677                                                            int64_t timeout);
 678
 679 #ifdef __cplusplus
 680 }
 681 #endif
 682
 683 #endif /* LTTNG_CHANNEL_H */