LTTng control library C API
Loading...
Searching...
No Matches
Modules | Data Structures | Enumerations | Functions
Domain and channel API
Recording session API
Collaboration diagram for Domain and channel API:

Modules

 Data stream infos
 
 Memory reclaim
 
 Recording event rule API
 

Data Structures

struct  lttng_channel
 Channel summary. More...
 
struct  lttng_channel_attr
 Attributes of a channel summary. More...
 
struct  lttng_domain
 Tracing domain summary. More...
 
struct  lttng_event_context
 Context field descriptor. More...
 
union  lttng_event_context_u
 perf counter or application-specific context field descriptor. More...
 
struct  lttng_event_perf_counter_ctx
 perf counter context field descriptor. More...
 

Enumerations

enum  lttng_buffer_type { LTTNG_BUFFER_PER_PID , LTTNG_BUFFER_PER_UID , LTTNG_BUFFER_GLOBAL }
 Buffering ownership model of a channel. More...
 
enum  lttng_channel_allocation_policy { LTTNG_CHANNEL_ALLOCATION_POLICY_PER_CPU , LTTNG_CHANNEL_ALLOCATION_POLICY_PER_CHANNEL }
 Buffer allocation policy of a channel. More...
 
enum  lttng_channel_get_data_stream_info_sets_status { LTTNG_CHANNEL_GET_DATA_STREAM_INFO_SETS_STATUS_OK , LTTNG_CHANNEL_GET_DATA_STREAM_INFO_SETS_STATUS_ERROR , LTTNG_CHANNEL_GET_DATA_STREAM_INFO_SETS_STATUS_INVALID_PARAMETER , LTTNG_CHANNEL_GET_DATA_STREAM_INFO_SETS_STATUS_UNSUPPORTED_DOMAIN }
 Return type of lttng_channel_get_data_stream_info_sets(). More...
 
enum  lttng_channel_preallocation_policy { LTTNG_CHANNEL_PREALLOCATION_POLICY_PREALLOCATE , LTTNG_CHANNEL_PREALLOCATION_POLICY_ON_DEMAND }
 Buffer preallocation policy of a channel. More...
 
enum  lttng_channel_status { LTTNG_CHANNEL_STATUS_OK , LTTNG_CHANNEL_STATUS_UNSET , LTTNG_CHANNEL_STATUS_INVALID }
 Status code for channel property accessors. More...
 
enum  lttng_domain_type {
  LTTNG_DOMAIN_NONE , LTTNG_DOMAIN_KERNEL , LTTNG_DOMAIN_UST , LTTNG_DOMAIN_JUL ,
  LTTNG_DOMAIN_LOG4J , LTTNG_DOMAIN_LOG4J2 , LTTNG_DOMAIN_PYTHON , LTTNG_DOMAIN_NR
}
 Tracing domain type (tracer type). More...
 
enum  lttng_event_context_type {
  LTTNG_EVENT_CONTEXT_PID , LTTNG_EVENT_CONTEXT_PROCNAME , LTTNG_EVENT_CONTEXT_PRIO , LTTNG_EVENT_CONTEXT_NICE ,
  LTTNG_EVENT_CONTEXT_VPID , LTTNG_EVENT_CONTEXT_TID , LTTNG_EVENT_CONTEXT_VTID , LTTNG_EVENT_CONTEXT_PPID ,
  LTTNG_EVENT_CONTEXT_VPPID , LTTNG_EVENT_CONTEXT_PTHREAD_ID , LTTNG_EVENT_CONTEXT_HOSTNAME , LTTNG_EVENT_CONTEXT_IP ,
  LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER , LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER , LTTNG_EVENT_CONTEXT_APP_CONTEXT , LTTNG_EVENT_CONTEXT_INTERRUPTIBLE ,
  LTTNG_EVENT_CONTEXT_PREEMPTIBLE , LTTNG_EVENT_CONTEXT_NEED_RESCHEDULE , LTTNG_EVENT_CONTEXT_MIGRATABLE , LTTNG_EVENT_CONTEXT_CALLSTACK_KERNEL ,
  LTTNG_EVENT_CONTEXT_CALLSTACK_USER , LTTNG_EVENT_CONTEXT_CGROUP_NS , LTTNG_EVENT_CONTEXT_IPC_NS , LTTNG_EVENT_CONTEXT_MNT_NS ,
  LTTNG_EVENT_CONTEXT_NET_NS , LTTNG_EVENT_CONTEXT_PID_NS , LTTNG_EVENT_CONTEXT_USER_NS , LTTNG_EVENT_CONTEXT_UTS_NS ,
  LTTNG_EVENT_CONTEXT_UID , LTTNG_EVENT_CONTEXT_EUID , LTTNG_EVENT_CONTEXT_SUID , LTTNG_EVENT_CONTEXT_GID ,
  LTTNG_EVENT_CONTEXT_EGID , LTTNG_EVENT_CONTEXT_SGID , LTTNG_EVENT_CONTEXT_VUID , LTTNG_EVENT_CONTEXT_VEUID ,
  LTTNG_EVENT_CONTEXT_VSUID , LTTNG_EVENT_CONTEXT_VGID , LTTNG_EVENT_CONTEXT_VEGID , LTTNG_EVENT_CONTEXT_VSGID ,
  LTTNG_EVENT_CONTEXT_TIME_NS , LTTNG_EVENT_CONTEXT_CPU_ID
}
 Context field type. More...
 
enum  lttng_event_output { LTTNG_EVENT_SPLICE , LTTNG_EVENT_MMAP }
 Channel output type. More...
 

Functions

int lttng_add_context (struct lttng_handle *handle, struct lttng_event_context *context_field_descriptor, const char *event_name, const char *channel_name)
 Makes the future event records of the channel named channel_name (or of a default channel or all the channels if NULL) within the recording session and tracing domain of handle have a context field described by context_field_descriptor.
 
struct lttng_channel * lttng_channel_create (struct lttng_domain *domain)
 Creates and returns a channel summary, setting the members of its lttng_channel::attr member to default values according to the tracing domain summary domain.
 
void lttng_channel_destroy (struct lttng_channel *channel)
 Destroys the channel summary channel.
 
enum lttng_error_code lttng_channel_get_allocation_policy (const struct lttng_channel *channel, enum lttng_channel_allocation_policy *policy)
 Sets *policy to the buffer allocation policy property of the channel summary channel.
 
enum lttng_channel_status lttng_channel_get_automatic_memory_reclamation_policy (const struct lttng_channel *channel, uint64_t *older_than_us)
 Sets *older_than_us to the age threshold (µs) of the automatic memory reclaim of the channel summary channel.
 
int lttng_channel_get_blocking_timeout (const struct lttng_channel *channel, int64_t *timeout)
 Sets *timeout to the blocking timeout property of the channel summary channel.
 
enum lttng_channel_get_data_stream_info_sets_status lttng_channel_get_data_stream_info_sets (const char *session_name, const char *channel_name, enum lttng_domain_type domain, const struct lttng_data_stream_info_sets **sets)
 Retrieves data stream info sets for the channel named channel_name in the recording session named session_name and tracing domain domain.
 
int lttng_channel_get_discarded_event_count (const struct lttng_channel *channel, uint64_t *count)
 Sets *count to the number of discarded event records of the channel summarized by channel.
 
int lttng_channel_get_lost_packet_count (const struct lttng_channel *channel, uint64_t *count)
 Sets *count to the number of discarded packets (sub-buffers) of the channel summarized by channel.
 
int lttng_channel_get_monitor_timer_interval (const struct lttng_channel *channel, uint64_t *period)
 Sets *period to the monitor timer period (µs) property of the channel summary channel.
 
enum lttng_channel_status lttng_channel_get_preallocation_policy (const struct lttng_channel *channel, enum lttng_channel_preallocation_policy *policy)
 Sets *policy to the buffer preallocation policy of the channel summary channel.
 
enum lttng_channel_status lttng_channel_get_watchdog_timer_interval (const struct lttng_channel *channel, uint64_t *period)
 Sets *period to the watchdog timer period (µs) property of the channel summary channel.
 
enum lttng_error_code lttng_channel_set_allocation_policy (struct lttng_channel *channel, enum lttng_channel_allocation_policy policy)
 Sets the buffer allocation policy property of the channel summary channel to policy.
 
enum lttng_channel_status lttng_channel_set_automatic_memory_reclamation_policy (struct lttng_channel *channel, uint64_t older_than_us)
 Sets the automatic memory reclaim policy of the channel summary channel to reclaim buffered data older than older_than_us µs.
 
int lttng_channel_set_blocking_timeout (struct lttng_channel *channel, int64_t timeout)
 Sets the blocking timeout property of the channel summary channel to timeout.
 
void lttng_channel_set_default_attr (struct lttng_domain *domain, struct lttng_channel_attr *attr)
 Sets the members of attr to their default values considering the tracing domain summary domain.
 
int lttng_channel_set_monitor_timer_interval (struct lttng_channel *channel, uint64_t period)
 Sets the monitor timer period property of the channel summary channel to period µs.
 
enum lttng_channel_status lttng_channel_set_preallocation_policy (struct lttng_channel *channel, enum lttng_channel_preallocation_policy policy)
 Sets the buffer preallocation policy property of the channel summary channel to policy.
 
enum lttng_channel_status lttng_channel_set_watchdog_timer_interval (struct lttng_channel *channel, uint64_t period)
 Sets the watchdog timer period property of the channel summary channel to period µs.
 
int lttng_disable_channel (struct lttng_handle *handle, const char *channel_name)
 Disables the channel named channel_name within the recording session handle handle.
 
int lttng_enable_channel (struct lttng_handle *handle, struct lttng_channel *channel)
 Creates or enables a channel summarized by channel within the recording session handle handle.
 
int lttng_list_events (const struct lttng_handle *handle, const char *channel_name, struct lttng_event **event_rules)
 Sets *event_rules to the descriptors of the recording event rules of the channel named channel_name within the recording session handle handle.
 

Detailed Description

Tracing domain

A tracing domain identifies a type of LTTng tracer.

A tracing domain has its own properties and features.

There are currently five available tracing domains:

Domain name Type enumerator
Linux kernel LTTNG_DOMAIN_KERNEL
User space LTTNG_DOMAIN_UST
java.util.logging (JUL) LTTNG_DOMAIN_JUL
Apache log4j 1.x LTTNG_DOMAIN_LOG4J
Apache Log4j 2 LTTNG_DOMAIN_LOG4J2
Python logging LTTNG_DOMAIN_PYTHON

A channel is always part of a tracing domain.

Many liblttng-ctl functions require a tracing domain type (sometimes within a recording session handle) to target specific tracers or to avoid ambiguity. For example, because the Linux kernel and user space tracing domains support named tracepoints as instrumentation points, you need to specify a tracing domain when you create a recording event rule with lttng_enable_event_with_exclusions() because both tracing domains could have LTTng tracepoints sharing the same name.

See also
The “TRACING DOMAIN” section of lttng-concepts(7).

Channel

A channel is an object which is responsible for a set of ring buffers.

Each ring buffer is divided into multiple sub-buffers. When a recording event rule matches an event, LTTng can record it to one or more sub-buffers of one or more channels.

A channel is always associated to a tracing domain. The java.util.logging, Apache log4j 1.x, Apache Log4j 2, and Python tracing domains each have a default channel which you can't configure.

Note that the some functions, like lttng_enable_event_with_exclusions(), can automatically create a default channel with sane defaults when no channel exists for the provided tracing domain.

A channel owns recording event rules.

A recording session contains channels that are members of tracing domains and contain recording event rules.

You can't destroy a channel.

Operations

The channel operations are:

Operation Means
Creation

  1. Call lttng_channel_create() with a tracing domain summary to create an initial channel summary.

    This function calls lttng_channel_set_default_attr() to set the properties of the created channel summary to default values depending on the tracing domain summary.

  2. Set the properties of the channel summary of step 1 through direct members or with dedicated setters.

    See the property table below.

  3. Create a recording session handle structure to specify the name of the recording session and the tracing domain of the channel to create.
  4. Call lttng_enable_channel() with the recording session handle of step 3 and the channel summary of step 1 o create the channel.
  5. Destroy the recording session handle with lttng_destroy_handle() and the channel summary with lttng_channel_destroy().
See also
lttng-enable-channel(1)
Basic property access See the property table below.
Recording event rule access
  1. Create a recording session handle with lttng_create_handle() to specify the name of the recording session and the summary of the tracing domain of the channel of which to get the recording event rule descriptors.

  2. Call lttng_list_events(), passing the recording session handle of step 1 and a channel name.

    This function sets a pointer to an array of recording event rule descriptors and returns the number of entries.

  3. Destroy the recording session handle of step 1 with lttng_destroy_handle().
  4. Access the properties of each recording event rule descriptor through structure members or using dedicated getters.
  5. When you're done with the array of recording event rule descriptors, free it with free().
Event record context field adding
  1. Initialize an lttng_event_context structure, setting its properties to describe the context field to be added.
  2. Create a recording session handle structure to specify the name of the recording session and the tracing domain of the channel to target.
  3. Call lttng_add_context() with the recording session handle of step 2 and the context field descriptor of step 1, optionally passing the name of the channel to target.
  4. Destroy the recording session handle with lttng_destroy_handle().
See also
lttng-add-context(1)
Memory reclaim See Memory reclaim.
Enabling

Use lttng_enable_channel().

See also
lttng-enable-channel(1)
Disabling

Use lttng_disable_channel().

See also
lttng-disable-channel(1)
Statistics

See:

Properties

The properties of a channel are:

Property name Description Access
Buffer ownership model See Buffer ownership model.

The lttng_domain::buf_type member for the containing tracing domain.

All the channels of a given tracing domain share the same buffer ownership model.

Buffer allocation policy See Buffer allocation policy.
Buffer preallocation policy See Buffer preallocation policy.
Automatic memory reclaim policy

LTTng may automatically reclaim the memory of a user space channel when its buffered data becomes older than a given maximal age.

This is more or less equivalent to automatically calling lttng_reclaim_channel_memory(). LTTng automatically evaluates the eligibility of sub-buffers for a memory reclaim operation at regular intervals (every half the configured maximal age, but also at least a period defined at build time) and reclaims sub-buffers of which the age of the closing time have exceeded the age threshold.

See Memory reclaim to learn more.

Data stream infos See Data stream infos. lttng_channel_get_data_stream_info_sets()
Event record loss mode See Event record loss mode. The lttng_channel_attr::overwrite member.
Sub-buffer size See Sub-buffer size and count. The lttng_channel_attr::subbuf_size member.
Sub-buffer count See Sub-buffer size and count. The lttng_channel_attr::num_subbuf member.
Maximum trace file size See Maximum trace file size and count. The lttng_channel_attr::tracefile_size member.
Maximum trace file count See Maximum trace file size and count. The lttng_channel_attr::tracefile_count member.
Read timer period See Read timer. The lttng_channel_attr::read_timer_interval member.
Switch timer period See Switch timer. The lttng_channel_attr::switch_timer_interval member.
Live timer period See Live timer. The live_timer_period parameter of lttng_session_descriptor_live_network_create() when you create the descriptor of a live recording session to contain the channel.
Monitor timer period See Monitor timer.
Watchdog timer period See Watchdog timer.
Output type (Linux kernel channel) Whether to use mmap() or splice(). The lttng_channel_attr::output member.
Blocking timeout (user space channel) How long to block (if ever) at the instrumentation point site when a sub-buffer is not available for applications executed with the LTTNG_UST_ALLOW_BLOCKING environment variable set.

All the properties above are immutable once a channel exists.

See also
The “CHANNEL AND RING BUFFER” section of lttng-concepts(7).

Buffer ownership model

The buffer ownership model of a channel specifies whether the system, each Unix user, or each process owns its own ring buffers (one per CPU or one for the whole channel).

When you read “allocate ring buffers” below, it's either one per CPU or one per channel, depending on the configured buffer allocation policy. The following diagrams assume a per-CPU allocation policy.

The available user space tracing buffer ownership models are, considering U is the Unix user of the process running liblttng-ctl:

Per-user buffering

Allocate ring buffers to be shared by all the instrumented processes of:

If U is root

Each Unix user.

Otherwise

U

Per-process buffering

Allocate ring buffers for each instrumented process of:

If U is root

All Unix users.

Otherwise

U

The per-process option tends to consume more memory than the per-user option because systems generally have more instrumented processes than Unix users running instrumented processes. However, the per-process ownership model ensures that one process having a high event throughput won't fill all the shared sub-buffers of the same Unix user, only its own. It also provides complete isolation between processes: one process cannot read or corrupt the trace data of another.

The buffer ownership model of a Linux kernel channel is always to allocate a single set of ring buffers–one per CPU–for the whole system (LTTNG_BUFFER_GLOBAL). This model is similar to the per-user option with a per-channel allocation policy, but with a single, global user “running” the kernel.

To set the buffer ownership model of a channel when you create it:

See also
The “Buffering scheme” section of lttng-concepts(7).

Buffer allocation policy

The buffer allocation policy of a channel specifies whether LTTng tracers allocate ring buffers per channel or per CPU (for a given user or process).

When you read “allocate one ring buffer” below, it's either one per user or one per process, depending on the configured buffer ownership model. The following diagrams assume a per-user ownership model.

The available user space tracing buffer allocation policies are, considering U is the Unix user of the process running liblttng-ctl:

Per-CPU buffering

Allocate one ring buffer for each CPU:

If U is root

For each Unix user/process.

Otherwise

For U.

When you create a channel having this policy, LTTng automatically adds a nonremovable LTTNG_EVENT_CONTEXT_CPU_ID context field (see lttng_add_context()).

Per-channel buffering

Allocate one ring buffer for the whole channel:

If U is root

For each Unix user/process.

Otherwise

For U.

When you create a channel having this policy, LTTng does not automatically adds an LTTNG_EVENT_CONTEXT_CPU_ID context field: add it manually afterwards with lttng_add_context() if needed.

As of LTTng-tools 15.2, the buffer allocation policy of a Linux kernel channel is always to allocate a single set of ring buffers–one per CPU–for the whole system.

To set the buffer allocation policy of a channel when you create it:

See also
The “Buffering scheme” section of lttng-concepts(7).

Buffer preallocation policy

The buffer preallocation policy of a user space channel specifies when LTTng allocates the backing memory for the ring buffers of the channel.

The available buffer preallocation policies are:

Preallocate

LTTng allocates the full backing memory for all ring buffers when you create the channel.

This policy provides consistent performance but uses more memory upfront. Use this policy to optimize instrumented application startup time.

On demand

LTTng allocates backing memory for ring buffers incrementally, as needed during tracing.

This policy uses less initial memory but may introduce slight performance overhead when allocating new memory during tracing.

As of LTTng-tools 15.2, the implicit buffer preallocation policy of a Linux kernel channel is always to preallocate backing memory.

To set the buffer preallocation policy of a channel when you create it:

Event record loss mode

When LTTng emits an event, LTTng can record it to a specific, available sub-buffer within the ring buffers of specific channels. When there's no space left in a sub-buffer, the tracer marks it as consumable and another, available sub-buffer starts receiving the following event records. An LTTng consumer daemon eventually consumes the marked sub-buffer, which returns to the available state.

In an ideal world, sub-buffers are consumed faster than they are filled. In the real world, however, all sub-buffers can be full at some point, leaving no space to record the following events.

By default, LTTng-modules and LTTng-UST are non-blocking tracers: when there's no available sub-buffer to record an event, it's acceptable to lose event records when the alternative would be to cause substantial delays in the execution of the instrumented application. LTTng privileges performance over integrity; it aims at perturbing the instrumented application as little as possible in order to make the detection of subtle race conditions and rare interrupt cascades possible.

Since LTTng 2.10, the LTTng user space tracer, LTTng-UST, supports a blocking mode: see lttng_channel_get_blocking_timeout() and lttng_channel_set_blocking_timeout().

When it comes to losing event records because there's no available sub-buffer, or because the blocking timeout of the channel is reached, the event record loss mode of the channel determines what to do. The available event record loss modes are:

Discard mode

Drop the newest event records until a sub-buffer becomes available.

This is the only available mode when you specify a blocking timeout with lttng_channel_set_blocking_timeout().

With this mode, LTTng increments a count of discarded event records when it discards an event record and saves this count to the trace. A trace reader can use the saved discarded event record count of the trace to decide whether or not to perform some analysis even if trace data is known to be missing.

Get the number of discarded event records of a channel with lttng_channel_get_discarded_event_count().

Overwrite mode

Clear the sub-buffer containing the oldest event records and start writing the newest event records there.

This mode is sometimes called flight recorder mode because it's similar to a flight recorder: always keep a fixed amount of the latest data. It's also similar to the roll mode of an oscilloscope.

Since LTTng 2.8, with this mode, LTTng writes to a given sub-buffer its sequence number within its data stream. With a local, network streaming, or live recording session, a trace reader can use such sequence numbers to report discarded packets. A trace reader can use the saved discarded sub-buffer (packet) count of the trace to decide whether or not to perform some analysis even if trace data is known to be missing.

Get the number of discarded packets (sub-buffers) of a channel with lttng_channel_get_lost_packet_count().

With this mode, LTTng doesn't write to the trace the exact number of lost event records in the lost sub-buffers.

Which mechanism you should choose depends on your context: prioritize the newest or the oldest event records in the ring buffer?

Beware that, in overwrite mode, the tracer abandons a whole sub-buffer as soon as a there's no space left for a new event record, whereas in discard mode, the tracer only discards the event record that doesn't fit.

To set the event record loss mode of a channel when you create it:

There are a few ways to decrease your probability of losing event records. The Sub-buffer size and count section shows how to fine-tune the sub-buffer size and count of a channel to virtually stop losing event records, though at the cost of greater memory usage.

See also
The “Event record loss mode” section of lttng-concepts(7).

Sub-buffer size and count

A channel has one or more ring buffer which LTTng allocates according to its configured ownership model and allocation policy.

To set the size of each sub-buffer the ring buffers of a channel have when you create it:

To set the number of sub-buffers each ring buffer of a channel has when you create it:

Note that LTTng switching the current sub-buffer of a ring buffer (marking a full one as consumable and switching to an available one for LTTng to record the next events) introduces noticeable CPU overhead. Knowing this, the following list presents a few practical situations along with how to configure the sub-buffer size and count for them:

High event throughput

In general, prefer large sub-buffers to lower the risk of losing event records.

Having larger sub-buffers also ensures a lower sub-buffer switching frequency.

The sub-buffer count is only meaningful if you create the channel in overwrite mode: in this case, if LTTng overwrites a sub-buffer, then the other sub-buffers are left unaltered.

Low event throughput

In general, prefer smaller sub-buffers since the risk of losing event records is low.

Because LTTng emits events less frequently, the sub-buffer switching frequency should remain low and therefore the overhead of the tracer shouldn't be a problem.

Low memory system

If your target system has a low memory limit, then prefer fewer first, then smaller sub-buffers.

Even if the system is limited in memory, you want to keep the sub-buffers as large as possible to avoid a high sub-buffer switching frequency.

Note that LTTng uses CTF as its trace format (see lttng_session_descriptor_set_trace_format()), which means event record data is very compact. For example, the average LTTng kernel event record weights about 32 bytes. Therefore, a sub-buffer size of 1 MiB is considered large.

The previous scenarios highlight the major trade-off between a few large sub-buffers and more, smaller sub-buffers: sub-buffer switching frequency vs. how many event records are lost in overwrite mode. Assuming a constant event throughput and using the overwrite mode, the two following configurations have the same ring buffer total size:

Two sub-buffers of 4 MiB each

Expect a very low sub-buffer switching frequency, but if LTTng ever needs to overwrite a sub-buffer, then half of the event records so far (4 MiB) are definitely lost.

Eight sub-buffers of 1 MiB each
Expect four times the tracer overhead of the configuration above, but if LTTng needs to overwrite a sub-buffer, then only the eighth of event records so far (1 MiB) are definitely lost.

In discard mode, the sub-buffer count parameter is pointless: use two sub-buffers and set their size according to your requirements.

See also
The “Sub-buffer size and count” section of lttng-concepts(7).

Maximum trace file size and count

By default, trace files can grow as large as needed.

To set the maximum size of each trace file that LTTng writes from the ring buffers of a channel when you create it:

When the size of a trace file reaches the fixed maximum size of the channel, LTTng creates another file to contain the next event records. LTTng appends a file count to each trace file name in this case.

If you set the trace file size attribute when you create a channel, then the maximum number of trace files that LTTng creates is unlimited by default.

To limit the size of each trace file that LTTng writes from the ring buffers of a channel when you create it:

When the number of trace files reaches the fixed maximum count of the channel, LTTng overwrites the oldest trace file. This mechanism is called trace file rotation.

Attention

Even if you don't limit the trace file count, always assume that LTTng manages all the trace files of the recording session.

In other words, there's no safe way to know if LTTng still holds a given trace file open with the trace file rotation feature.

The only way to obtain an unmanaged, self-contained LTTng trace before you destroy the recording session is with the recording session rotation feature, which is available since LTTng 2.11.

See also
The “Maximum trace file size and count” section of lttng-concepts(7).

Timers

Each channel can have up to four optional timers:

Switch timer

When this timer expires, a sub-buffer switch happens: for each ring buffer of the channel, LTTng marks the current sub-buffer as consumable and switches to an available one to record the next events.

A switch timer is useful to ensure that LTTng consumes and commits trace data to trace files or to a distant relay daemon (see lttng-relayd(8)) periodically in case of a low event throughput.

Such a timer is also convenient when you use large sub-buffers to cope with a sporadic high event throughput, even if the throughput is otherwise low.

To set the period of the switch timer of a channel when you create it:

A channel only has a switch timer when its recording session is not in live mode. lttng_enable_channel() ignores the lttng_channel_attr::switch_timer_interval member with a live recording session. For a live recording session, the live timer plays the role of the switch timer.

Live timer

Like the switch timer, but for a channel which belongs to a live recording session.

If this timer expires but there's no sub-buffer to consume, then LTTng sends a message with a timestamp to the connected relay daemon (see lttng-relayd(8)) so that its live readers can progress.

To set the period of the live timer of a channel when you create its recording session:

Note
All the channels of a live recording session share the same live timer period.
Read timer

When this timer expires, LTTng checks for full, consumable sub-buffers.

By default, the LTTng tracers use an asynchronous message mechanism to signal a full sub-buffer so that a consumer daemon can consume it.

When such messages must be avoided, for example in real-time applications, use this timer instead.

To set the period of the read timer of a channel when you create it:

Monitor timer

When this timer expires, the consumer daemon samples some channel statistics to evaluate the following trigger conditions:

If you disable the monitor timer of a channel C, then:

  • The consumed data size value of the recording session of C could be wrong for triggers with a “recording session consumed data size becomes greater than” condition: the consumed data size of C won't be part of the grand total.

  • Triggers with a “channel buffer usage becomes greater than” or “channel buffer usage becomes less than” condition for C will never fire.

    See Trigger API to learn more about triggers.

To set the period of the monitor timer of a channel when you create it:

Watchdog timer

When this timer expires, LTTng performs health checks that detect recoverable issues and trigger corrective actions to keep trace recording running smoothly for the channel.

As of LTTng-tools 15.2, the only health check is:

Sub-buffer stall detection

With a user space channel having a per-user ownership model, an instrumented application currently writing to a sub-buffer may crash and make said sub-buffer “stalled”, that is, never released and unusable. This can reduce the effective capacity of the channel or even halt the consumption altogether.

When the watchdog timer of a channel expires and LTTng detects this condition, it marks the stalled sub-buffer consumable/readable again.

Note
A process needs to terminate for the sub-buffer to be considered stalled: a SIGSTOP signal doesn't qualify.

To set the period of the watchdog timer of a channel when you create it:

See also
The “Timers” section of lttng-concepts(7).

Enumeration Type Documentation

◆ lttng_buffer_type

enum lttng_buffer_type

Buffering ownership model of a channel.

See Buffer ownership model to learn more.

Enumerator
LTTNG_BUFFER_PER_PID 

Per-process buffering.

LTTNG_BUFFER_PER_UID 

Per-user buffering.

LTTNG_BUFFER_GLOBAL 

Global (Linux kernel) buffering.

◆ lttng_channel_allocation_policy

enum lttng_channel_allocation_policy

Buffer allocation policy of a channel.

Enumerator
LTTNG_CHANNEL_ALLOCATION_POLICY_PER_CPU 

Per-CPU buffering

LTTNG_CHANNEL_ALLOCATION_POLICY_PER_CHANNEL 

Per-channel buffering

◆ lttng_channel_get_data_stream_info_sets_status

enum lttng_channel_get_data_stream_info_sets_status

Return type of lttng_channel_get_data_stream_info_sets().

Error status enumerators have a negative value.

Enumerator
LTTNG_CHANNEL_GET_DATA_STREAM_INFO_SETS_STATUS_OK 

Success.

LTTNG_CHANNEL_GET_DATA_STREAM_INFO_SETS_STATUS_ERROR 

Other error.

LTTNG_CHANNEL_GET_DATA_STREAM_INFO_SETS_STATUS_INVALID_PARAMETER 

Unsatisfied precondition.

◆ lttng_channel_preallocation_policy

enum lttng_channel_preallocation_policy

Buffer preallocation policy of a channel.

Enumerator
LTTNG_CHANNEL_PREALLOCATION_POLICY_PREALLOCATE 

Preallocate sub-buffers.

LTTNG_CHANNEL_PREALLOCATION_POLICY_ON_DEMAND 

Allocate sub-buffers as needed.

◆ lttng_channel_status

enum lttng_channel_status

Status code for channel property accessors.

Enumerator
LTTNG_CHANNEL_STATUS_OK 

Success.

LTTNG_CHANNEL_STATUS_UNSET 

Property is unset.

LTTNG_CHANNEL_STATUS_INVALID 

Unsatisfied precondition.

◆ lttng_domain_type

enum lttng_domain_type

Tracing domain type (tracer type).

Enumerator
LTTNG_DOMAIN_NONE 

None.

LTTNG_DOMAIN_KERNEL 

Linux kernel.

LTTNG_DOMAIN_UST 

User space.

LTTNG_DOMAIN_JUL 

java.util.logging (JUL).

LTTNG_DOMAIN_LOG4J 

Apache log4j 1.x.

LTTNG_DOMAIN_LOG4J2 

Apache Log4j 2.

LTTNG_DOMAIN_PYTHON 

Python logging.

◆ lttng_event_context_type

enum lttng_event_context_type

Context field type.

The following table indicates, for each enumerator, its description, for which tracing domain it's available, and the data type and the name of the resulting context field in traces.

All the context field types below, except for LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER, LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER, and LTTNG_EVENT_CONTEXT_APP_CONTEXT, are said to be statically known: they have a dedicated enumerator, their value is some specific system state, and recording them adds an event record context field with a designated name.

Enumerator Description Tracing domain Field type Field name
LTTNG_EVENT_CONTEXT_PID Process ID LTTNG_DOMAIN_KERNEL Integer pid
LTTNG_EVENT_CONTEXT_PROCNAME Process name LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST String procname
LTTNG_EVENT_CONTEXT_PRIO Process priority LTTNG_DOMAIN_KERNEL Integer prio
LTTNG_EVENT_CONTEXT_NICE Nice value of the process LTTNG_DOMAIN_KERNEL Integer nice
LTTNG_EVENT_CONTEXT_VPID Virtual process ID LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer vpid
LTTNG_EVENT_CONTEXT_TID Thread ID LTTNG_DOMAIN_KERNEL Integer tid
LTTNG_EVENT_CONTEXT_VTID Virtual thread ID LTTNG_DOMAIN_KERNEL Integer vtid
LTTNG_EVENT_CONTEXT_PPID ID of the parent process LTTNG_DOMAIN_KERNEL Integer ppid
LTTNG_EVENT_CONTEXT_VPPID Virtual ID of the parent process LTTNG_DOMAIN_KERNEL Integer vppid
LTTNG_EVENT_CONTEXT_PTHREAD_ID POSIX thread ID LTTNG_DOMAIN_KERNEL Integer pthread_id
LTTNG_EVENT_CONTEXT_HOSTNAME Hostname LTTNG_DOMAIN_KERNEL String hostname
LTTNG_EVENT_CONTEXT_IP Instruction pointer LTTNG_DOMAIN_UST Integer ip
LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER

Per-CPU perf counter.

If the lttng_event_context::ctx member of an lttng_event_context structure is LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER, then the lttng_event_context_u::perf_counter member of lttng_event_context::u selects a specific per-CPU perf counter.

LTTNG_DOMAIN_KERNEL Integer Depends on the selected perf counter
LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER

Per-thread perf counter.

If the lttng_event_context::ctx member of an lttng_event_context structure is LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER, then the lttng_event_context_u::perf_counter member of lttng_event_context::u selects a specific per-thread perf counter.

LTTNG_DOMAIN_UST Integer Depends on the selected perf counter
LTTNG_EVENT_CONTEXT_APP_CONTEXT

Application-specific context.

If the lttng_event_context::ctx member of an lttng_event_context structure is LTTNG_EVENT_CONTEXT_APP_CONTEXT, then the lttng_event_context_u::app_ctx member of of lttng_event_context::u selects a specific application-specific context.

LTTNG_DOMAIN_JUL, LTTNG_DOMAIN_LOG4J, or LTTNG_DOMAIN_LOG4J2 Integer or string Depends on the selected application-specific context
LTTNG_EVENT_CONTEXT_INTERRUPTIBLE Whether or not the process is interruptible LTTNG_DOMAIN_KERNEL Integer (0 or 1) interruptible
LTTNG_EVENT_CONTEXT_PREEMPTIBLE Whether or not the process is preemptible LTTNG_DOMAIN_KERNEL Integer (0 or 1) preemptible
LTTNG_EVENT_CONTEXT_NEED_RESCHEDULE Whether or not the process needs a reschedule LTTNG_DOMAIN_KERNEL Integer (0 or 1) need_reschedule
LTTNG_EVENT_CONTEXT_MIGRATABLE Whether or not the process is migratable LTTNG_DOMAIN_KERNEL Integer (0 or 1) migratable
LTTNG_EVENT_CONTEXT_CALLSTACK_KERNEL Linux kernel call stack LTTNG_DOMAIN_KERNEL Dynamic-length array of integers (instruction pointers) callstack_kernel
LTTNG_EVENT_CONTEXT_CALLSTACK_USER

User space call stack.

Only supported on IA-32 and x86-64 architectures.

LTTNG_DOMAIN_KERNEL Dynamic-length array of integers (instruction pointers) callstack_user
LTTNG_EVENT_CONTEXT_CGROUP_NS

Control group root directory namespace ID.

See also
cgroup_namespaces(7)
LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer cgroup_ns
LTTNG_EVENT_CONTEXT_IPC_NS

System V IPC and POSIX message queue namespace ID.

See also
ipc_namespaces(7)
LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer ipc_ns
LTTNG_EVENT_CONTEXT_MNT_NS

Mount point namespace ID.

See also
mount_namespaces(7)
LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer mnt_ns
LTTNG_EVENT_CONTEXT_NET_NS

Networking namespace ID.

See also
network_namespaces(7)
LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer net_ns
LTTNG_EVENT_CONTEXT_PID_NS

Process ID namespace ID.

See also
pid_namespaces(7)
LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer pid_ns
LTTNG_EVENT_CONTEXT_USER_NS

User and group ID namespace ID.

See also
user_namespaces(7)
LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer user_ns
LTTNG_EVENT_CONTEXT_UTS_NS

Hostname and NIS domain name namespace ID.

See also
uts_namespaces(7)
LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer uts_ns
LTTNG_EVENT_CONTEXT_TIME_NS

Boot and monotonic clock namespace ID.

See also
time_namespaces(7)
LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer time_ns
LTTNG_EVENT_CONTEXT_UID User ID LTTNG_DOMAIN_KERNEL Integer uid
LTTNG_EVENT_CONTEXT_EUID Effective user ID LTTNG_DOMAIN_KERNEL Integer euid
LTTNG_EVENT_CONTEXT_SUID Set owner user ID LTTNG_DOMAIN_KERNEL Integer suid
LTTNG_EVENT_CONTEXT_GID Group ID LTTNG_DOMAIN_KERNEL Integer gid
LTTNG_EVENT_CONTEXT_EGID Effective group ID LTTNG_DOMAIN_KERNEL Integer egid
LTTNG_EVENT_CONTEXT_SGID Set owner group ID LTTNG_DOMAIN_KERNEL Integer sgid
LTTNG_EVENT_CONTEXT_VUID Virtual user ID LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer vuid
LTTNG_EVENT_CONTEXT_VEUID Virtual effective user ID LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer veuid
LTTNG_EVENT_CONTEXT_VSUID Virtual set owner user ID LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer vsuid
LTTNG_EVENT_CONTEXT_VGID Virtual group ID LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer vgid
LTTNG_EVENT_CONTEXT_VEGID Virtual effective group ID LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer vegid
LTTNG_EVENT_CONTEXT_VSGID Virtual set owner group ID LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer vsgid
LTTNG_EVENT_CONTEXT_CPU_ID CPU ID LTTNG_DOMAIN_KERNEL and LTTNG_DOMAIN_UST Integer cpu_id
Enumerator
LTTNG_EVENT_CONTEXT_PID 

Process ID.

LTTNG_EVENT_CONTEXT_PROCNAME 

Process name.

LTTNG_EVENT_CONTEXT_PRIO 

Process priority.

LTTNG_EVENT_CONTEXT_NICE 

Nice value of the process.

LTTNG_EVENT_CONTEXT_VPID 

Virtual process ID.

LTTNG_EVENT_CONTEXT_TID 

Thread ID.

LTTNG_EVENT_CONTEXT_VTID 

Virtual thread ID.

LTTNG_EVENT_CONTEXT_PPID 

ID of the parent process.

LTTNG_EVENT_CONTEXT_VPPID 

Virtual ID of the parent process.

LTTNG_EVENT_CONTEXT_PTHREAD_ID 

POSIX thread ID.

LTTNG_EVENT_CONTEXT_HOSTNAME 

Hostname.

LTTNG_EVENT_CONTEXT_IP 

Instruction pointer.

LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER 

Per-CPU perf counter.

LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER 

Per-thread perf counter.

LTTNG_EVENT_CONTEXT_APP_CONTEXT 

Application-specific context.

LTTNG_EVENT_CONTEXT_INTERRUPTIBLE 

Whether or not the process is interruptible.

LTTNG_EVENT_CONTEXT_PREEMPTIBLE 

Whether or not the process is preemptible.

LTTNG_EVENT_CONTEXT_NEED_RESCHEDULE 

Whether or not the process needs a reschedule.

LTTNG_EVENT_CONTEXT_MIGRATABLE 

Whether or not the process is migratable.

LTTNG_EVENT_CONTEXT_CALLSTACK_KERNEL 

Linux kernel call stack.

LTTNG_EVENT_CONTEXT_CALLSTACK_USER 

User space call stack.

LTTNG_EVENT_CONTEXT_CGROUP_NS 

Control group root directory namespace ID.

LTTNG_EVENT_CONTEXT_IPC_NS 

System V IPC and POSIX message queue namespace ID.

LTTNG_EVENT_CONTEXT_MNT_NS 

Mount point namespace ID.

LTTNG_EVENT_CONTEXT_NET_NS 

Networking namespace ID.

LTTNG_EVENT_CONTEXT_PID_NS 

Process ID namespace ID.

LTTNG_EVENT_CONTEXT_USER_NS 

User and group ID namespace ID.

LTTNG_EVENT_CONTEXT_UTS_NS 

Hostname and NIS domain name namespace ID.

LTTNG_EVENT_CONTEXT_UID 

User ID namespace ID.

LTTNG_EVENT_CONTEXT_EUID 

Effective user ID namespace ID.

LTTNG_EVENT_CONTEXT_SUID 

Set owner user ID namespace ID.

LTTNG_EVENT_CONTEXT_GID 

Group ID namespace ID.

LTTNG_EVENT_CONTEXT_EGID 

Effective group ID namespace ID.

LTTNG_EVENT_CONTEXT_SGID 

Set owner group ID namespace ID.

LTTNG_EVENT_CONTEXT_VUID 

Virtual user ID namespace ID.

LTTNG_EVENT_CONTEXT_VEUID 

Virtual effective user ID namespace ID.

LTTNG_EVENT_CONTEXT_VSUID 

Virtual set owner user ID namespace ID.

LTTNG_EVENT_CONTEXT_VGID 

Virtual group ID namespace ID.

LTTNG_EVENT_CONTEXT_VEGID 

Virtual effective group ID namespace ID.

LTTNG_EVENT_CONTEXT_VSGID 

Virtual set owner group ID namespace ID.

LTTNG_EVENT_CONTEXT_TIME_NS 

Boot and monotonic clock namespace ID.

LTTNG_EVENT_CONTEXT_CPU_ID 

CPU ID.

◆ lttng_event_output

enum lttng_event_output

Channel output type.

Enumerator
LTTNG_EVENT_SPLICE 

Use the splice(2) system call.

LTTNG_EVENT_MMAP 

Use the mmap(2) system call.

Function Documentation

◆ lttng_add_context()

int lttng_add_context ( struct lttng_handle *  handle,
struct lttng_event_context *  context_field_descriptor,
const char *  event_name,
const char *  channel_name 
)
extern

Makes the future event records of the channel named channel_name (or of a default channel or all the channels if NULL) within the recording session and tracing domain of handle have a context field described by context_field_descriptor.

Context values (for example, the ID of the current process, the instruction pointer, or the hostname) are always available during tracing. This function makes LTTng record a specific context value as a field for each future event record of the selected channel(s).

Parameters
[in]handleRecording session handle which contains the name of the recording session and the summary of the tracing domain which own the channel(s) to select.
[in]context_field_descriptorDescriptor of the context field to add to each event record of the selected channel(s).
[in]event_nameUnused: must be NULL.
[in]channel_name

Name of the channel to select.

If NULL, then:

If the recording session and tracing domain of handle have no channels

LTTng creates a new, default channel named channel0 within handle which becomes the selected channel.

Otherwise
LTTng selects all the channels of handle.
Returns
0 or a positive value

Success

Negative lttng_error_code enumerator
Error
Precondition

◆ lttng_channel_create()

struct lttng_channel * lttng_channel_create ( struct lttng_domain *  domain)
extern

Creates and returns a channel summary, setting the members of its lttng_channel::attr member to default values according to the tracing domain summary domain.

This function internally calls

lttng_channel_set_default_attr(domain, &channel->attr);
lttng_channel_set_default_attr
void lttng_channel_set_default_attr(struct lttng_domain *domain, struct lttng_channel_attr *attr)
Sets the members of attr to their default values considering the tracing domain summary domain.

where channel is the returned channel summary.

After you create a channel summary with this function, you can modify its properties and call lttng_enable_channel() to create and enable a channel.

Parameters
[in]domainTracing domain summary to consider to set the members of the lttng_channel::attr member of the returned structure to default values.
Returns

New channel summary.

Destroy the returned channel summary with lttng_channel_destroy().

Precondition
  • domain is not NULL.
See also
lttng_channel_destroy() – Destroys a channel summary.

◆ lttng_channel_destroy()

void lttng_channel_destroy ( struct lttng_channel *  channel)
extern

Destroys the channel summary channel.

Note
This function doesn't destroy the channel which channel summarizes: the only way to destroy a channel is to destroy its recording session.
Parameters
[in]channel

Channel summary to destroy.

May be NULL.

◆ lttng_channel_get_allocation_policy()

enum lttng_error_code lttng_channel_get_allocation_policy ( const struct lttng_channel *  channel,
enum lttng_channel_allocation_policy *  policy 
)
extern

Sets *policy to the buffer allocation policy property of the channel summary channel.

This property only applies to user space channels.

Parameters
[in]channelSummary of the channel of which to get the buffer allocation policy.
[out]policyOn success, this function sets *policy to the buffer allocation policy of channel.
Return values
LTTNG_OKSuccess.
LTTNG_ERR_INVALIDUnsatisfied precondition.
Precondition
See also
lttng_channel_set_allocation_policy() – Sets the buffer allocation policy property of a channel summary.

◆ lttng_channel_get_automatic_memory_reclamation_policy()

enum lttng_channel_status lttng_channel_get_automatic_memory_reclamation_policy ( const struct lttng_channel *  channel,
uint64_t *  older_than_us 
)
extern

Sets *older_than_us to the age threshold (µs) of the automatic memory reclaim of the channel summary channel.

This property only applies to user space channels.

Parameters
[in]channelSummary of the channel of which to get the automatic memory reclaim maximal age.
[out]older_than_usOn success, this function sets *older_than_us to the age threshold (µs) of the automatic memory reclaim.
Return values
LTTNG_CHANNEL_STATUS_OKSuccess.
LTTNG_CHANNEL_STATUS_UNSETThe automatic memory reclaim age threshold is not set for this channel.
LTTNG_CHANNEL_STATUS_INVALIDUnsatisfied precondition.
Precondition

◆ lttng_channel_get_blocking_timeout()

int lttng_channel_get_blocking_timeout ( const struct lttng_channel *  channel,
int64_t *  timeout 
)
extern

Sets *timeout to the blocking timeout property of the channel summary channel.

This property only applies to user space channels.

Parameters
[in]channelSummary of the channel of which to get the blocking timeout.
[out]timeout

On success, this function sets *timeout to one of:

-1

The blocking timeout of channel is infinite.

0

Blocking is disabled for channel.

Otherwise
The blocking timeout of channel is *timeout µs.
Returns
0

Success.

-LTTNG_ERR_INVALID (negative)
Unsatisfied precondition.
Precondition
See also
lttng_channel_set_blocking_timeout() – Sets the blocking timeout property of a channel summary.

◆ lttng_channel_get_data_stream_info_sets()

enum lttng_channel_get_data_stream_info_sets_status lttng_channel_get_data_stream_info_sets ( const char *  session_name,
const char *  channel_name,
enum lttng_domain_type  domain,
const struct lttng_data_stream_info_sets **  sets 
)
extern

Retrieves data stream info sets for the channel named channel_name in the recording session named session_name and tracing domain domain.

Only user space domains are supported. The content and availability of memory usage information may vary depending on tracer support.

Parameters
[in]session_nameName of the recording session which contains the targeted channel.
[in]channel_nameName of the channel for which to get data stream info sets.
[in]domainTracing domain of the targeted channel for which to get data stream info sets.
[out]sets

On success, this function sets *sets to a the data stream information sets for the targeted channel.

Destroy *sets with lttng_data_stream_info_sets_destroy().

Return values
LTTNG_CHANNEL_GET_DATA_STREAM_INFO_SETS_STATUS_OKSuccess.
LTTNG_CHANNEL_GET_DATA_STREAM_INFO_SETS_STATUS_INVALID_PARAMETERUnsatisfied precondition.
LTTNG_CHANNEL_GET_DATA_STREAM_INFO_SETS_STATUS_ERROROther error.
Precondition

◆ lttng_channel_get_discarded_event_count()

int lttng_channel_get_discarded_event_count ( const struct lttng_channel *  channel,
uint64_t *  count 
)
extern

Sets *count to the number of discarded event records of the channel summarized by channel.

In discard mode, LTTng discards an event record when there's no sub-buffer left to write it.

lttng_list_channels() sets a pointer to an array of all the channel summaries of a given recording session and tracing domain.

Parameters
[in]channelSummary of the channel of which to get the number of discarded event records.
[out]countOn success, this function sets *count to the number of discarded event records of the channel summarized by channel.
Returns
0

Success.

-LTTNG_ERR_INVALID (negative)
Unsatisfied precondition.
Precondition
See also
lttng_channel_get_lost_packet_count() – Returns the number of discarded packets (sub-buffers) of a channel.

◆ lttng_channel_get_lost_packet_count()

int lttng_channel_get_lost_packet_count ( const struct lttng_channel *  channel,
uint64_t *  count 
)
extern

Sets *count to the number of discarded packets (sub-buffers) of the channel summarized by channel.

In overwrite mode, LTTng discards a whole sub-buffer when there's no sub-buffer left to record an event.

lttng_list_channels() sets a pointer to an array of all the channel summaries of a given recording session and tracing domain.

Parameters
[in]channelSummary of the channel of which to get the number of discarded packets.
[out]countOn success, this function sets *count to the number of discarded packets of the channel summarized by channel.
Returns
0

Success.

-LTTNG_ERR_INVALID (negative)
Unsatisfied precondition.
Precondition
See also
lttng_channel_get_discarded_event_count() – Returns the number of discarded event records of a channel.

◆ lttng_channel_get_monitor_timer_interval()

int lttng_channel_get_monitor_timer_interval ( const struct lttng_channel *  channel,
uint64_t *  period 
)
extern

Sets *period to the monitor timer period (µs) property of the channel summary channel.

Parameters
[in]channelSummary of the channel of which to get the monitor timer period.
[out]periodOn success, this function sets *period to the monitor timer period (µs) property of channel.
Returns
0

Success.

-LTTNG_ERR_INVALID (negative)
Unsatisfied precondition.
Precondition
  • channel is not NULL.
  • period is not NULL.
See also
lttng_channel_set_monitor_timer_interval() – Sets the monitor timer period property of a channel summary.

◆ lttng_channel_get_preallocation_policy()

enum lttng_channel_status lttng_channel_get_preallocation_policy ( const struct lttng_channel *  channel,
enum lttng_channel_preallocation_policy *  policy 
)
extern

Sets *policy to the buffer preallocation policy of the channel summary channel.

This property only applies to user space channels.

Parameters
[in]channelSummary of the channel of which to get the buffer preallocation policy.
[out]policyOn success, this function sets *policy to the buffer preallocation policy of channel.
Return values
LTTNG_CHANNEL_STATUS_OKSuccess.
LTTNG_CHANNEL_STATUS_INVALIDUnsatisfied precondition.
Precondition

◆ lttng_channel_get_watchdog_timer_interval()

enum lttng_channel_status lttng_channel_get_watchdog_timer_interval ( const struct lttng_channel *  channel,
uint64_t *  period 
)
extern

Sets *period to the watchdog timer period (µs) property of the channel summary channel.

Parameters
[in]channelSummary of the channel of which to get the watchdog timer period.
[out]periodOn success, this function sets *period to the watchdog timer period (µs) property of channel.
Return values
LTTNG_CHANNEL_STATUS_OKSuccess.
LTTNG_CHANNEL_STATUS_INVALIDUnsatisfied precondition.
LTTNG_CHANNEL_STATUS_UNSETWatchdog timer isn't set.
Precondition
  • channel is not NULL.
  • period is not NULL.
See also
lttng_channel_get_watchdog_timer_interval() – Returns the watchdog timer period property of a channel summary.

◆ lttng_channel_set_allocation_policy()

enum lttng_error_code lttng_channel_set_allocation_policy ( struct lttng_channel *  channel,
enum lttng_channel_allocation_policy  policy 
)
extern

Sets the buffer allocation policy property of the channel summary channel to policy.

This property only applies to user space channels.

Parameters
[in]channelChannel summary of which to set the buffer allocation policy to policy.
[in]policyBuffer allocation policy to set.
Return values
LTTNG_OKSuccess.
LTTNG_ERR_INVALIDUnsatisfied precondition.
Precondition
See also
lttng_channel_get_allocation_policy() – Returns the buffer allocation policy property of a channel summary.

◆ lttng_channel_set_automatic_memory_reclamation_policy()

enum lttng_channel_status lttng_channel_set_automatic_memory_reclamation_policy ( struct lttng_channel *  channel,
uint64_t  older_than_us 
)
extern

Sets the automatic memory reclaim policy of the channel summary channel to reclaim buffered data older than older_than_us µs.

This property only applies to user space channels.

Parameters
[in]channelChannel summary of which to set the automatic memory reclaim policy.
[in]older_than_usMinimum age (µs) of buffered data to consider to reclaim memory.
Return values
LTTNG_CHANNEL_STATUS_OKSuccess.
LTTNG_CHANNEL_STATUS_INVALIDUnsatisfied precondition.
Precondition

◆ lttng_channel_set_blocking_timeout()

int lttng_channel_set_blocking_timeout ( struct lttng_channel *  channel,
int64_t  timeout 
)
extern

Sets the blocking timeout property of the channel summary channel to timeout.

This property only applies to user space channels.

Parameters
[in]channelChannel summary of which to set the blocking timeout to timeout.
[in]timeout

One of:

-1

The blocking timeout of channel is infinite.

0

Blocking is disabled for channel.

Otherwise
The blocking timeout of channel is timeout µs.
Returns
0

Success.

-LTTNG_ERR_INVALID (negative)
Unsatisfied precondition.
Precondition
See also
lttng_channel_get_blocking_timeout() – Returns the blocking timeout property of a channel summary.

◆ lttng_channel_set_default_attr()

void lttng_channel_set_default_attr ( struct lttng_domain *  domain,
struct lttng_channel_attr *  attr 
)
extern

Sets the members of attr to their default values considering the tracing domain summary domain.

Use this function on an lttng_channel::attr member.

Parameters
[in]domainTracing domain summary to consider to set the members of attr to their default values.
[in]attrStructure of which to set the members to their default values.
Precondition
  • domain is not NULL.
  • attr is not NULL.

◆ lttng_channel_set_monitor_timer_interval()

int lttng_channel_set_monitor_timer_interval ( struct lttng_channel *  channel,
uint64_t  period 
)
extern

Sets the monitor timer period property of the channel summary channel to period µs.

Parameters
[in]channelChannel summary of which to set the monitor timer period to period µs.
[in]periodMonitor timer period property to set.
Returns
0

Success.

-LTTNG_ERR_INVALID (negative)
Unsatisfied precondition.
Precondition
  • channel is not NULL.
See also
lttng_channel_get_monitor_timer_interval() – Returns the monitor timer period property of a channel summary.

◆ lttng_channel_set_preallocation_policy()

enum lttng_channel_status lttng_channel_set_preallocation_policy ( struct lttng_channel *  channel,
enum lttng_channel_preallocation_policy  policy 
)
extern

Sets the buffer preallocation policy property of the channel summary channel to policy.

This property only applies to user space channels.

Parameters
[in]channelChannel summary of which to set the buffer preallocation policy to policy.
[in]policyBuffer preallocation policy to set.
Return values
LTTNG_CHANNEL_STATUS_OKSuccess.
LTTNG_CHANNEL_STATUS_INVALIDUnsatisfied precondition.
Precondition

◆ lttng_channel_set_watchdog_timer_interval()

enum lttng_channel_status lttng_channel_set_watchdog_timer_interval ( struct lttng_channel *  channel,
uint64_t  period 
)
extern

Sets the watchdog timer period property of the channel summary channel to period µs.

Parameters
[in]channelChannel summary of which to set the watchdog timer period to period µs.
[in]periodWatchdog timer period property to set.
Return values
LTTNG_CHANNEL_STATUS_OKSuccess.
#LTTNG_CHANNEL_STATUS__INVALIDUnsatisfied precondition.
Precondition
See also
lttng_channel_set_watchdog_timer_interval() – Sets the watchdog timer period property of a channel summary.

◆ lttng_disable_channel()

int lttng_disable_channel ( struct lttng_handle *  handle,
const char *  channel_name 
)
extern

Disables the channel named channel_name within the recording session handle handle.

Parameters
[in]handleRecording session handle which contains the name of the recording session and the summary of the tracing domain which own the channel to disable.
[in]channel_nameName of the channel to disable within handle.
Returns
0 or a positive value

Success

Negative lttng_error_code enumerator
Error
Precondition
  • liblttng-ctl can connect to a session daemon.
  • handle is not NULL.
  • handle->session_name is a valid (null-terminated) C string.
  • handle->session_name names an accessible recording session within the connected session daemon.
  • handle->domain is valid as per the documentation of lttng_domain.
  • channel_name is not NULL.
  • channel_name names an existing channel within the recording session and tracing domain of handle.
See also
lttng_enable_channel() – Creates or enables a channel.

◆ lttng_enable_channel()

int lttng_enable_channel ( struct lttng_handle *  handle,
struct lttng_channel *  channel 
)
extern

Creates or enables a channel summarized by channel within the recording session handle handle.

This function, depending on channel->name:

channel->name names an existing channel within the recording session and tracing domain of handle

Enables the existing channel.

In this case, this function only uses channel->name, ignoring all the other properties of channel.

Otherwise
Creates and enables a new channel, considering all the properties of channel.
Parameters
[in]handleRecording session handle which contains the name of the recording session and the summary of the tracing domain which own the channel to create or enable.
[in]channelSummary of the channel to create or enable.
Returns
0 or a positive value

Success

Negative lttng_error_code enumerator
Error
Precondition
  • liblttng-ctl can connect to a session daemon.
  • handle is not NULL.
  • handle->session_name is a valid (null-terminated) C string.
  • handle->session_name names an accessible recording session within the connected session daemon.
  • handle->domain is valid as per the documentation of lttng_domain.
  • channel is not NULL.
  • If this function must create a new channel, then channel->attr is valid.
  • If this function must create a new channel, then handle->session_name names a recording session which never became active (started) since its creation.
  • If this function must create a new channel, then all the existing channels of handle have the same buffer ownership model.
See also
lttng_disable_channel() – Disables a channel.

◆ lttng_list_events()

int lttng_list_events ( const struct lttng_handle *  handle,
const char *  channel_name,
struct lttng_event **  event_rules 
)
extern

Sets *event_rules to the descriptors of the recording event rules of the channel named channel_name within the recording session handle handle.

Parameters
[in]handleRecording session handle which contains the name of the recording session and the summary of the tracing domain which own the channel (named channel_name) of which to get the recording event rule descriptors.
[in]channel_nameName of the channel, within handle, of which to get all the recording event rule descriptors.
[out]event_rules

On success, this function sets *event_rules to the recording event rule descriptors.

Free *event_rules with free().

Returns
The number of items in *event_rules on success, or a negative lttng_error_code enumerator otherwise.
Precondition
  • liblttng-ctl can connect to a session daemon.
  • handle is not NULL.
  • handle->session_name is a valid (null-terminated) C string.
  • handle->session_name names an accessible recording session within the connected session daemon.
  • handle->domain is valid as per the documentation of lttng_domain.
  • channel_name is not NULL.
  • channel_name names an existing channel within the recording session and tracing domain of handle.
  • event_rules is not NULL.