2 * Copyright (C) 2014 David Goulet <dgoulet@efficios.com>
4 * SPDX-License-Identifier: LGPL-2.1-only
8 #ifndef LTTNG_CHANNEL_H
9 #define LTTNG_CHANNEL_H
11 #include <lttng/domain.h>
12 #include <lttng/event.h>
13 #include <lttng/lttng-export.h>
22 * Tracer channel attributes. For both kernel and user-space.
24 * The structures should be initialized to zero before use.
26 #define LTTNG_CHANNEL_ATTR_PADDING1 LTTNG_SYMBOL_NAME_LEN + 12
30 Attributes of a \link #lttng_channel channel summary\endlink.
34 The lttng_channel::attr member is an instance of such a structure.
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.
39 \anchor api-channel-valid-attr-struct A \em valid #lttng_channel_attr
40 structure satisfies the following constraints:
47 <td>lttng_channel_attr::overwrite
50 <td>lttng_channel_attr::subbuf_size
55 <td>lttng_channel_attr::num_subbuf
61 struct lttng_channel_attr
{
64 \ref api-channel-er-loss-mode "Event record loss mode".
71 The \ref api-channel-er-loss-mode "event record loss mode"
73 <em>\ref api-channel-discard-mode "discard"</em>.
77 The event record loss mode of the channel is
78 <em>\ref api-channel-overwrite-mode "overwrite"</em>.
82 The event record loss mode of the channel is the default
83 value of its \lt_obj_session:
86 <dt>\ref api-session-snapshot-mode "Snapshot mode"
94 int overwrite
; /* -1: session default, 1: overwrite, 0: discard */
98 \ref api-channel-sub-buf-size-count "Sub-buffer size"
101 uint64_t subbuf_size
; /* bytes, power of 2 */
105 \ref api-channel-sub-buf-size-count "Sub-buffer count".
107 uint64_t num_subbuf
; /* power of 2 */
111 \ref api-channel-switch-timer "Switch timer period" (µs),
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".
118 unsigned int switch_timer_interval
; /* usec */
120 /// \ref api-channel-read-timer "Read timer period" (µs).
121 unsigned int read_timer_interval
; /* usec */
123 /// Output type (Linux kernel channel).
124 enum lttng_event_output output
; /* splice, mmap */
126 /* LTTng 2.1 padding limit */
130 \ref api-channel-max-trace-file-size-count "Maximum trace file size"
131 (bytes), or 0 for unlimited.
133 uint64_t tracefile_size
; /* bytes */
137 \ref api-channel-max-trace-file-size-count "Maximum trace file count",
140 uint64_t tracefile_count
; /* number of tracefiles */
142 /* LTTng 2.3 padding limit */
146 \ref api-channel-live-timer "Live timer period" (µs), if
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.
155 Only available if the \lt_obj_session which
156 owns this channel is in \ref api-session-live-mode "live mode".
158 unsigned int live_timer_interval
; /* usec */
160 /* LTTng 2.7 padding limit */
161 uint32_t align_to_64
;
167 char padding
[LTTNG_CHANNEL_ATTR_PADDING1
];
171 * Channel information structure. For both kernel and user-space.
173 * The structures should be initialized to zero before use.
175 #define LTTNG_CHANNEL_PADDING1 16
179 \lt_obj_c_channel summary.
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).
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.
190 Most properties are part of the lttng_channel::attr member, but the
191 following ones have their own dedicated accessors:
194 <dt>\ref api-channel-monitor-timer "Monitor timer" period
196 - lttng_channel_get_monitor_timer_interval()
197 - lttng_channel_set_monitor_timer_interval()
199 <dt>\ref api-channel-blocking-timeout "Blocking timeout"
201 - lttng_channel_get_blocking_timeout()
202 - lttng_channel_set_blocking_timeout()
205 Create a channel summary with lttng_channel_create().
207 Destroy a channel summary with lttng_channel_destroy().
209 struct lttng_channel
{
211 char name
[LTTNG_SYMBOL_NAME_LEN
];
215 1 if this \lt_obj_channel is enabled, or 0 otherwise.
217 @sa lttng_enable_channel() --
218 Creates or enables a channel.
219 @sa lttng_disable_channel() --
224 /// Other properties.
225 struct lttng_channel_attr attr
;
227 char padding
[LTTNG_CHANNEL_PADDING1
];
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}.
238 This function internally calls
241 lttng_channel_set_default_attr(domain, &channel->attr);
244 where \c channel is the returned channel summary.
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.
251 Tracing domain summary to consider to set the members of the
252 lttng_channel::attr member of the returned structure to default
259 Destroy the returned channel summary with lttng_channel_destroy().
262 @lt_pre_not_null{domain}
264 @sa lttng_channel_destroy() --
265 Destroys a channel summary.
267 LTTNG_EXPORT
extern struct lttng_channel
*lttng_channel_create(struct lttng_domain
*domain
);
271 Destroys the \lt_obj_channel summary \lt_p{channel}.
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
283 Channel summary to destroy.
288 LTTNG_EXPORT
extern void lttng_channel_destroy(struct lttng_channel
*channel
);
292 Sets \lt_p{*channels} to the summaries of the
293 \lt_obj_channels of the recording session handle \lt_p{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.
303 <strong>On success</strong>, this function sets \lt_p{*channels} to
304 the summaries of the channels.
306 Free \lt_p{*channels} with <code>free()</code>.
310 The number of items in \lt_p{*channels} on success, or a \em
311 negative #lttng_error_code enumerator otherwise.
314 @lt_pre_not_null{handle}
315 @lt_pre_valid_c_str{handle->session_name}
316 @lt_pre_sess_exists{handle->session_name}
318 \lt_p{handle->domain} is valid as per the documentation of
320 @lt_pre_not_null{channels}
322 LTTNG_EXPORT
extern int lttng_list_channels(struct lttng_handle
*handle
,
323 struct lttng_channel
**channels
);
327 Creates or enables a \lt_obj_channel summarized by \lt_p{channel}
328 within the recording session handle \lt_p{handle}.
332 This function, depending on \lt_p{channel->name}:
336 \lt_p{channel->name} names an existing
337 channel within the \lt_obj_session and
338 \lt_obj_domain of \lt_p{handle}
340 Enables the existing channel.
342 In this case, this function only uses \lt_p{channel->name}, ignoring
343 all the other properties of \lt_p{channel}.
347 Creates and enables a new channel, considering all the properties of
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.
356 Summary of the channel to create or enable.
359 0 on success, or a \em negative #lttng_error_code enumerator
363 @lt_pre_not_null{handle}
364 @lt_pre_valid_c_str{handle->session_name}
365 @lt_pre_sess_exists{handle->session_name}
367 \lt_p{handle->domain} is valid as per the documentation of
369 @lt_pre_not_null{channel}
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".
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
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".
384 @sa lttng_disable_channel() --
387 LTTNG_EXPORT
extern int lttng_enable_channel(struct lttng_handle
*handle
,
388 struct lttng_channel
*channel
);
392 Disables the \lt_obj_channel named \lt_p{channel_name} within the
393 recording session handle \lt_p{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}.
405 0 on success, or a \em negative #lttng_error_code enumerator
409 @lt_pre_not_null{handle}
410 @lt_pre_valid_c_str{handle->session_name}
411 @lt_pre_sess_exists{handle->session_name}
413 \lt_p{handle->domain} is valid as per the documentation of
415 @lt_pre_not_null{channel_name}
417 \lt_p{channel_name} names an existing channel within the recording
418 session and tracing domain of \lt_p{handle}.
420 @sa lttng_enable_channel() --
421 Creates or enables a channel.
423 LTTNG_EXPORT
extern int lttng_disable_channel(struct lttng_handle
*handle
,
424 const char *channel_name
);
428 Sets the members of \lt_p{attr} to their default values considering
429 the \lt_obj_domain summary \lt_p{domain}.
433 Use this function on an lttng_channel::attr member.
436 Tracing domain summary to consider to set the members of \lt_p{attr}
437 to their default values.
439 Structure of which to set the members to their default values.
441 @lt_pre_not_null{domain}
442 @lt_pre_not_null{attr}
444 LTTNG_EXPORT
extern void lttng_channel_set_default_attr(struct lttng_domain
*domain
,
445 struct lttng_channel_attr
*attr
);
449 Sets \lt_p{*count} to the number of discarded event
450 records of the \lt_obj_channel summarized by \lt_p{channel}.
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.
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.
461 Summary of the channel of which to get the number of discarded
464 <strong>On success</strong>, this function sets \lt_p{*count} to
465 the number of discarded event records of the channel summarized
469 0 on success, or a \em negative #lttng_error_code enumerator
472 @lt_pre_not_null{channel}
474 You obtained \lt_p{channel} with lttng_list_channels().
476 The lttng_channel_attr::overwrite member of \lt_p{channel->attr}
478 @lt_pre_not_null{count}
480 @sa lttng_channel_get_lost_packet_count() --
481 Returns the number of discarded packets (sub-buffers) of a channel.
483 LTTNG_EXPORT
extern int lttng_channel_get_discarded_event_count(struct lttng_channel
*channel
,
488 Sets \lt_p{*count} to the number of discarded packets (sub-buffers)
489 of the \lt_obj_channel summarized by \lt_p{channel}.
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.
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.
500 Summary of the channel of which to get the number of discarded
503 <strong>On success</strong>, this function sets \lt_p{*count} to
504 the number of discarded packets of the channel summarized
508 0 on success, or a \em negative #lttng_error_code enumerator
511 @lt_pre_not_null{channel}
513 You obtained \lt_p{channel} with lttng_list_channels().
515 The lttng_channel_attr::overwrite member of \lt_p{channel->attr}
517 @lt_pre_not_null{count}
519 @sa lttng_channel_get_discarded_event_count() --
520 Returns the number of discarded event records of a channel.
522 LTTNG_EXPORT
extern int lttng_channel_get_lost_packet_count(struct lttng_channel
*channel
,
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}.
534 Summary of the channel of which to get the monitor timer period.
536 <strong>On success</strong>, this function sets \lt_p{*period} to
537 the monitor timer period (µs) property of \lt_p{channel}.
540 0 on success, or a \em negative #lttng_error_code enumerator
543 @lt_pre_not_null{channel}
544 @lt_pre_not_null{period}
546 @sa lttng_channel_set_monitor_timer_interval() --
547 Sets the monitor timer period property of a channel summary.
549 LTTNG_EXPORT
extern int lttng_channel_get_monitor_timer_interval(struct lttng_channel
*channel
,
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} µs.
561 Channel summary of which to set the monitor timer period
562 to \lt_p{period} µs.
564 Monitor timer period property to set.
567 0 on success, or a \em negative #lttng_error_code enumerator
570 @lt_pre_not_null{channel}
572 \lt_p{period} ≥ 1
574 @sa lttng_channel_get_monitor_timer_interval() --
575 Returns the monitor timer period property of a channel summary.
577 LTTNG_EXPORT
extern int lttng_channel_set_monitor_timer_interval(struct lttng_channel
*channel
,
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}.
588 This property only applies to \link #LTTNG_DOMAIN_UST user space\endlink
592 Summary of the channel of which to get the blocking timeout.
595 <strong>On success</strong>, this function sets \lt_p{*timeout} to
601 The blocking timeout of \lt_p{channel} is infinite.
605 Blocking is disabled for \lt_p{channel}.
609 The blocking timeout of \lt_p{channel} is
610 \lt_p{*timeout} µs.
615 0 on success, or a \em negative #lttng_error_code enumerator
618 @lt_pre_not_null{channel}
620 The \lt_obj_domain type of \lt_p{channel} is #LTTNG_DOMAIN_UST.
621 @lt_pre_not_null{timeout}
623 @sa lttng_channel_set_blocking_timeout() --
624 Sets the blocking timeout property of a channel summary.
626 LTTNG_EXPORT
extern int lttng_channel_get_blocking_timeout(struct lttng_channel
*channel
,
631 Sets the \ref api-channel-blocking-timeout "blocking timeout"
632 property of the channel summary \lt_p{channel} to
637 This property only applies to \link #LTTNG_DOMAIN_UST user space\endlink
641 Channel summary of which to set the blocking timeout
650 The blocking timeout of \lt_p{channel} is infinite.
654 Blocking is disabled for \lt_p{channel}.
658 The blocking timeout of \lt_p{channel} is
659 \lt_p{timeout} µs.
664 0 on success, or a \em negative #lttng_error_code enumerator
667 @lt_pre_not_null{channel}
669 The \lt_obj_domain type of \lt_p{channel} is #LTTNG_DOMAIN_UST.
671 \lt_p{timeout} ≥ -1
673 @sa lttng_channel_get_blocking_timeout() --
674 Returns the blocking timeout property of a channel summary.
676 LTTNG_EXPORT
extern int lttng_channel_set_blocking_timeout(struct lttng_channel
*channel
,
683 #endif /* LTTNG_CHANNEL_H */