 |
LTTng control library C API
|
|
LTTng control library C API
|
Modules | |
| 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... | |
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. | |
| 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. | |
| int | lttng_channel_get_discarded_event_count (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 (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_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. | |
| 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. | |
| 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 (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. | |
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.
lttng-concepts(7).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.
You can't destroy a channel.
The channel operations are:
| Operation | Means |
|---|---|
| Creation |
|
| Basic property access | See the property table below. |
| Recording event rule access |
|
| Event record context field adding |
|
| Enabling |
|
| Disabling |
|
| Statistics | See: |
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. | |
| 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. | |
| 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.
lttng-concepts(7).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:
Allocate ring buffers to be shared by all the instrumented processes of:
root Each Unix user.
U
Allocate ring buffers for each instrumented process of:
root All Unix users.
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.
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:
Set the lttng_domain::buf_type member of the structure which you pass within the lttng_handle structure to lttng_enable_channel().
Note that, for a given recording session, all the channels of a given tracing domain must share the same buffer ownership model.
lttng-concepts(7).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:
Allocate one ring buffer for each CPU:
root For each Unix user/process.
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()).
Allocate one ring buffer for the whole channel:
root For each Unix user/process.
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 14.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:
lttng-concepts(7).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:
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().
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.
lttng-concepts(7).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:
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.
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.
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, 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:
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.
In discard mode, the sub-buffer count parameter is pointless: use two sub-buffers and set their size according to your requirements.
lttng-concepts(7).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.
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.
lttng-concepts(7).Each channel can have up to four optional timers:
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.
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:
live_timer_period parameter when you call lttng_session_descriptor_live_network_create() to create a live recording session descriptor to pass to lttng_create_session_ext().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:
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:
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:
lttng-concepts(7). | 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. |
Buffer allocation policy of a channel.
| Enumerator | |
|---|---|
| LTTNG_CHANNEL_ALLOCATION_POLICY_PER_CPU | |
| LTTNG_CHANNEL_ALLOCATION_POLICY_PER_CHANNEL | |
| enum lttng_domain_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.
| enum lttng_event_output |
|
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).
| [in] | handle | Recording 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_descriptor | Descriptor of the context field to add to each event record of the selected channel(s). |
| [in] | event_name | Unused: must be NULL. |
| [in] | channel_name | Name of the channel to select. If
|
Success
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->session_name names a recording session which never became active (started) since its creation.handle->domain is valid (you passed a tracing domain summary to lttng_create_handle() when you created handle).context_field_descriptor is valid according to the documentation of lttng_event_context.event_name is NULL.NULL, channel_name names an existing channel within the recording session and tracing domain of handle.
|
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
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.
| [in] | domain | Tracing domain summary to consider to set the members of the lttng_channel::attr member of the returned structure to default values. |
New channel summary.
Destroy the returned channel summary with lttng_channel_destroy().
domain is not NULL.
|
extern |
Destroys the channel summary channel.
channel summarizes: the only way to destroy a channel is to destroy its recording session.| [in] | channel | Channel summary to destroy. May be |
|
extern |
Sets *policy to the buffer allocation policy property of the channel summary channel.
This property only applies to user space channels.
| [in] | channel | Summary of the channel of which to get the buffer allocation policy. |
| [out] | policy | On success, this function sets *policy to the buffer allocation policy of channel. |
| LTTNG_OK | Success. |
| LTTNG_ERR_INVALID | Unsatisfied precondition. |
channel is not NULL.channel is LTTNG_DOMAIN_UST.policy is not NULL.
|
extern |
Sets *timeout to the blocking timeout property of the channel summary channel.
This property only applies to user space channels.
| [in] | channel | Summary of the channel of which to get the blocking timeout. |
| [out] | timeout | On success, this function sets
|
Success.
channel is not NULL.channel is LTTNG_DOMAIN_UST.timeout is not NULL.
|
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.
| [in] | channel | Summary of the channel of which to get the number of discarded event records. |
| [out] | count | On success, this function sets *count to the number of discarded event records of the channel summarized by channel. |
Success.
channel is not NULL.channel with lttng_list_channels().channel->attr is 0.count is not NULL.
|
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.
| [in] | channel | Summary of the channel of which to get the number of discarded packets. |
| [out] | count | On success, this function sets *count to the number of discarded packets of the channel summarized by channel. |
Success.
channel is not NULL.channel with lttng_list_channels().channel->attr is 1.count is not NULL.
|
extern |
Sets *period to the monitor timer period (µs) property of the channel summary channel.
| [in] | channel | Summary of the channel of which to get the monitor timer period. |
| [out] | period | On success, this function sets *period to the monitor timer period (µs) property of channel. |
Success.
channel is not NULL.period is not NULL.
|
extern |
Sets the buffer allocation policy property of the channel summary channel to policy.
This property only applies to user space channels.
| [in] | channel | Channel summary of which to set the buffer allocation policy to policy. |
| [in] | policy | Buffer allocation policy to set. |
| LTTNG_OK | Success. |
| LTTNG_ERR_INVALID | Unsatisfied precondition. |
channel is not NULL.channel is LTTNG_DOMAIN_UST.
|
extern |
Sets the blocking timeout property of the channel summary channel to timeout.
This property only applies to user space channels.
| [in] | channel | Channel summary of which to set the blocking timeout to timeout. |
| [in] | timeout | One of:
|
Success.
channel is not NULL.channel is LTTNG_DOMAIN_UST.timeout ≥ -1
|
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.
| [in] | domain | Tracing domain summary to consider to set the members of attr to their default values. |
| [in] | attr | Structure of which to set the members to their default values. |
domain is not NULL.attr is not NULL.
|
extern |
Sets the monitor timer period property of the channel summary channel to period µs.
| [in] | channel | Channel summary of which to set the monitor timer period to period µs. |
| [in] | period | Monitor timer period property to set. |
Success.
channel is not NULL.period ≥ 1
|
extern |
Disables the channel named channel_name within the recording session handle handle.
| [in] | handle | Recording 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_name | Name of the channel to disable within handle. |
Success
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.
|
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.
channel. | [in] | handle | Recording 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] | channel | Summary of the channel to create or enable. |
Success
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.channel->attr is valid.handle->session_name names a recording session which never became active (started) since its creation.handle have the same buffer ownership model.
|
extern |
Sets *event_rules to the descriptors of the recording event rules of the channel named channel_name within the recording session handle handle.
| [in] | handle | Recording 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_name | Name of the channel, within handle, of which to get all the recording event rule descriptors. |
| [out] | event_rules | On success, this function sets Free |
*event_rules on success, or a negative lttng_error_code enumerator otherwise.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. 
1.9.8