Collaboration diagram for Recording event rule API:

Data Structures
struct	lttng_event
	Recording event rule descriptor. More...

union	lttng_event_attr_u
	Linux kprobe/kretprobe recording event rule configuration. More...

struct	lttng_event_probe_attr
	Legacy Linux kprobe/kretprobe location. More...

Enumerations
enum	lttng_event_type { LTTNG_EVENT_ALL , LTTNG_EVENT_TRACEPOINT , LTTNG_EVENT_PROBE , LTTNG_EVENT_FUNCTION , LTTNG_EVENT_SYSCALL , LTTNG_EVENT_USERSPACE_PROBE }
	Instrumentation point type condition of a recording event rule, or instrumentation point type when lttng_list_tracepoints() or lttng_list_syscalls() creates the lttng_event structure. More...

enum	lttng_loglevel { LTTNG_LOGLEVEL_EMERG , LTTNG_LOGLEVEL_ALERT , LTTNG_LOGLEVEL_CRIT , LTTNG_LOGLEVEL_ERR , LTTNG_LOGLEVEL_WARNING , LTTNG_LOGLEVEL_NOTICE , LTTNG_LOGLEVEL_INFO , LTTNG_LOGLEVEL_DEBUG_SYSTEM , LTTNG_LOGLEVEL_DEBUG_PROGRAM , LTTNG_LOGLEVEL_DEBUG_PROCESS , LTTNG_LOGLEVEL_DEBUG_MODULE , LTTNG_LOGLEVEL_DEBUG_UNIT , LTTNG_LOGLEVEL_DEBUG_FUNCTION , LTTNG_LOGLEVEL_DEBUG_LINE , LTTNG_LOGLEVEL_DEBUG }
	Value of the instrumentation point log level condition of an LTTng user space tracepoint recording event rule descriptor. More...

enum	lttng_loglevel_jul { LTTNG_LOGLEVEL_JUL_OFF , LTTNG_LOGLEVEL_JUL_SEVERE , LTTNG_LOGLEVEL_JUL_WARNING , LTTNG_LOGLEVEL_JUL_INFO , LTTNG_LOGLEVEL_JUL_CONFIG , LTTNG_LOGLEVEL_JUL_FINE , LTTNG_LOGLEVEL_JUL_FINER , LTTNG_LOGLEVEL_JUL_FINEST , LTTNG_LOGLEVEL_JUL_ALL }
	Value of the instrumentation point log level condition of a `java.util.logging` recording event rule. More...

enum	lttng_loglevel_log4j { LTTNG_LOGLEVEL_LOG4J_OFF , LTTNG_LOGLEVEL_LOG4J_FATAL , LTTNG_LOGLEVEL_LOG4J_ERROR , LTTNG_LOGLEVEL_LOG4J_WARN , LTTNG_LOGLEVEL_LOG4J_INFO , LTTNG_LOGLEVEL_LOG4J_DEBUG , LTTNG_LOGLEVEL_LOG4J_TRACE , LTTNG_LOGLEVEL_LOG4J_ALL }
	Value of the instrumentation point log level condition of an Apache log4j 1.x recording event rule. More...

enum	lttng_loglevel_log4j2 { LTTNG_LOGLEVEL_LOG4J2_OFF , LTTNG_LOGLEVEL_LOG4J2_FATAL , LTTNG_LOGLEVEL_LOG4J2_ERROR , LTTNG_LOGLEVEL_LOG4J2_WARN , LTTNG_LOGLEVEL_LOG4J2_INFO , LTTNG_LOGLEVEL_LOG4J2_DEBUG , LTTNG_LOGLEVEL_LOG4J2_TRACE , LTTNG_LOGLEVEL_LOG4J2_ALL }
	Value of the instrumentation point log level condition of a Apache Log4j 2 recording event rule. More...

enum	lttng_loglevel_python { LTTNG_LOGLEVEL_PYTHON_CRITICAL , LTTNG_LOGLEVEL_PYTHON_ERROR , LTTNG_LOGLEVEL_PYTHON_WARNING , LTTNG_LOGLEVEL_PYTHON_INFO , LTTNG_LOGLEVEL_PYTHON_DEBUG , LTTNG_LOGLEVEL_PYTHON_NOTSET }
	Value of the instrumentation point log level condition of a Python recording event rule. More...

enum	lttng_loglevel_type { LTTNG_EVENT_LOGLEVEL_ALL , LTTNG_EVENT_LOGLEVEL_RANGE , LTTNG_EVENT_LOGLEVEL_SINGLE }
	Operand of the instrumentation point log level condition of a recording event rule. More...

Functions
int	lttng_disable_event (struct lttng_handle handle, const char event_rule_name, const char *channel_name)
	Alias of lttng_disable_event_ext() which creates a temporary recording event rule descriptor, settings its lttng_event::name member to `event_rule_name` if not `NULL` and its lttng_event::type member to LTTNG_EVENT_ALL.

int	lttng_disable_event_ext (struct lttng_handle handle, struct lttng_event event_rule, const char channel_name, const char filter_expr)
	Disables recording event rules by instrumentation point type and event name condition within the event record channel named `channel_name` (or within a default event record channel if `NULL`) within the recording session handle `handle`.

int	lttng_enable_event (struct lttng_handle handle, struct lttng_event event_rule, const char *channel_name)
	Alias of lttng_enable_event_with_exclusions() which passes the event payload and context filter expression of `event_rule` as the `filter_expr` parameter and the event name exclusion patterns of `event_rule` as the `event_name_exclusion_count` and `event_name_exclusions` parameters.

int	lttng_enable_event_with_exclusions (struct lttng_handle handle, struct lttng_event event_rule, const char channel_name, const char filter_expr, int event_name_exclusion_count, char **event_name_exclusions)
	Creates or enables a recording event rule described by `event_rule`, having the event payload and context filter expression `filter_expr` and the event name exclusion patterns `event_name_exclusions`, within the event record channel named `channel_name` (or within a default event record channel if `NULL`) within the recording session handle `handle`.

int	lttng_enable_event_with_filter (struct lttng_handle handle, struct lttng_event event_rule, const char channel_name, const char filter_expr)
	Alias of lttng_enable_event_with_exclusions() which passes the the event name exclusion patterns of `event_rule` as the `event_name_exclusion_count` and `event_name_exclusions` parameters.

struct lttng_event *	lttng_event_create (void)
	Creates and returns an empty recording event rule descriptor.

void	lttng_event_destroy (struct lttng_event *event_rule)
	Destroys the recording event rule descriptor `event_rule`.

int	lttng_event_get_exclusion_name (const struct lttng_event event_rule, size_t index, const char *event_name_exclusion)
	Sets `*event_name_exclusion` to the event name exclusion pattern at index `index` of the recording event rule described by `event_rule`.

int	lttng_event_get_exclusion_name_count (const struct lttng_event *event_rule)
	Returns the number of event name exclusion patterns of the recording event rule described by `event_rule`.

int	lttng_event_get_filter_expression (const struct lttng_event event_rule, const char *filter_expr)
	Sets `*filter_expr` to the event payload and context filter expression of the recording event rule described by `event_rule`.

const struct lttng_userspace_probe_location *	lttng_event_get_userspace_probe_location (const struct lttng_event *event_rule)
	Returns the Linux user space probe location of the recording event rule described by `event_rule`.

int	lttng_event_set_userspace_probe_location (struct lttng_event event_rule, struct lttng_userspace_probe_location location)
	Sets the Linux user space probe location of the recording event rule described by `event_rule` to `location`.

Detailed Description

Concepts

An instrumentation point is a point, within a piece of software, which, when executed, creates an LTTng event. See Instrumentation point listing API to learn how to list the available instrumentation points.

An event rule is a set of conditions to match a set of events.

A recording event rule is a specific type of event rule of which the action is to serialize and write the matched event as an event record to a sub-buffer of its attached event record channel.

An event record has a name and fields.

When LTTng creates an event E, a recording event rule ER is said to match E when E satisfies all the conditions of ER. This concept is similar to a regular expression which matches a set of strings.

When a recording event rule matches an event, LTTng emits the event, therefore attempting to record it.

Attention

The event creation and emission processes are documentation concepts to help understand the journey from an instrumentation point to an event record.

The actual creation of an event can be costly because LTTng needs to evaluate the arguments of the instrumentation point.

In practice, LTTng implements various optimizations for the Linux kernel and user space tracing domains to avoid actually creating an event when the tracer knows, thanks to properties which are independent from the event payload and current context, that it would never emit such an event. Those properties are:

The instrumentation point type.
The instrumentation point name (or event name).
The instrumentation point log level.
The status (enabled or disabled) of the rule itself.
The status (enabled or disabled) of the event record channel containing the rule.
The activity (started or stopped) of the recording session containing the rule.
Whether or not the process for which LTTng would create the event is allowed to record events.

In other words: if, for a given instrumentation point IP, the LTTng tracer knows that it would never emit an event, executing IP represents a simple boolean variable check and, for a Linux kernel recording event rule, a few current process attribute checks.

You always attach a recording event rule to an event record channel, which belongs to a recording session, when you create it. An event record channel owns recording event rules.

When multiple matching recording event rules are attached to the same event record channel, LTTng attempts to serialize and record the matched event once.

Logical path from an instrumentation point to an event record.

As of LTTng-tools 16.2, you cannot remove a recording event rule: it exists as long as its recording session exists.

Operations

The recording event rule operations are:

Operation	Means
Creation	Call lttng_event_create() to create an initial recording event rule descriptor. Set the properties of the recording event rule descriptor of step 1 through direct members or with dedicated setters. See the property table below. Create a recording session handle structure to specify the name of the recording session and the tracing domain of the recording event rule to create. Call lttng_enable_event_with_exclusions() with the recording session handle of step 3, the recording event rule descriptor of step 1, the name of a event record channel to which to attach the created recording event rule, and, depending on the selected function, other properties to create the rule. Destroy the recording session handle with lttng_destroy_handle() and the recording event rule descriptor with lttng_event_destroy(). See also `lttng-enable-event(1)`
Property access	See: The members of lttng_event lttng_event_get_userspace_probe_location() lttng_event_set_userspace_probe_location() lttng_event_get_filter_expression() lttng_event_get_exclusion_name_count() lttng_event_get_exclusion_name() See also Recording event rule conditions.
Enabling	With an lttng_event instance which comes from lttng_list_events(), use lttng_enable_event(). Otherwise, use lttng_enable_event_with_exclusions(). See also `lttng-enable-event(1)`
Disabling	Use lttng_disable_event() or lttng_disable_event_ext(). See also `lttng-disable-event(1)`

Recording event rule conditions

For LTTng to emit and record an event E, E must satisfy all the conditions of a recording event rule ER, that is:

Explicit conditions

You set the following conditions when you create ER from some recording event rule descriptor event_rule (lttng_event).

Name	Description
Instrumentation point type	E satisfies the instrumentation point type condition of ER if the instrumentation point from which LTTng creates E is, depending on the tracing domain which contains ER: LTTNG_DOMAIN_KERNEL Depending on `event_rule.type`: LTTNG_EVENT_TRACEPOINT An LTTng kernel tracepoint, that is, a statically defined point in the source code of the kernel image or of a kernel module with LTTng kernel tracer macros. See also lttng_list_tracepoints() LTTNG_EVENT_SYSCALL The entry and exit of a Linux kernel system call. See also lttng_list_syscalls() LTTNG_EVENT_PROBE A Linux kprobe, that is, a single probe dynamically placed in the compiled kernel code. `event_rule.attr.probe` indicates the kprobe location, while `event_rule.name` is the name of the created kprobe instrumentation point (future event name). The payload of a Linux kprobe event is empty. LTTNG_EVENT_FUNCTION A Linux kretprobe, that is, two probes dynamically placed at the entry and exit of a function in the compiled kernel code. `event_rule.attr.probe` indicates the kretprobe location, while `event_rule.name` is the name of the created kretprobe instrumentation point (future event name). The payload of a Linux kretprobe event is empty. LTTNG_EVENT_USERSPACE_PROBE A Linux user space probe, that is, a single probe dynamically placed at the entry of a compiled user space application/library function through the kernel. Set and get the location of the user space probe with lttng_event_set_userspace_probe_location() and lttng_event_get_userspace_probe_location(). `event_rule.name` is the name of the created user space probe instrumentation point (future event name). The payload of a Linux user space probe event is empty. LTTNG_DOMAIN_UST An LTTng user space tracepoint, that is, a statically defined point in the source code of a C/C++ application/library with LTTng user space tracer macros. `event_rule.type` must be LTTNG_EVENT_TRACEPOINT. See also lttng_list_tracepoints() LTTNG_DOMAIN_JUL LTTNG_DOMAIN_LOG4J LTTNG_DOMAIN_PYTHON A Java/Python logging statement. `event_rule.type` must be LTTNG_EVENT_TRACEPOINT. See also lttng_list_tracepoints()
Event name	An event E satisfies the event name condition of ER if the two following statements are true: `event_rule.name` matches, depending on `event_rule.type` (see Instrumentation point type above): LTTNG_EVENT_TRACEPOINT The full name of the LTTng tracepoint or Java/Python logger from which LTTng creates E. Note that the full name of a user space tracepoint is `PROVIDER:NAME`, where `PROVIDER` is the tracepoint provider name and `NAME` is the tracepoint name. LTTNG_EVENT_SYSCALL The name of the system call, without any `sys_` prefix, from which LTTng creates E. See also Event record name. If the tracing domain containing ER is LTTNG_DOMAIN_UST: none of the event name exclusion patterns of `event_rule` matches the full name of the user space tracepoint from which LTTng creates E. Set the event name exclusion patterns of `event_rule` when you call lttng_enable_event_with_exclusions(). Get the event name exclusion patterns of `event_rule` with lttng_event_get_exclusion_name_count() and lttng_event_get_exclusion_name(). This condition is only meaningful when `event_rule.type` is LTTNG_EVENT_TRACEPOINT or LTTNG_EVENT_SYSCALL: it's always satisfied for the other instrumentation point types. In all cases, `event_rule.name` and the event name exclusion patterns of `event_rule` are globbing patterns: the `` character means “match anything”. To match a literal `` character, use `\*`.
Instrumentation point log level	An event E satisfies the instrumentation point log level condition of ER if, depending on `event_rule.loglevel_type`, the log level of the LTTng user space tracepoint or logging statement from which LTTng creates E is: LTTNG_EVENT_LOGLEVEL_ALL Anything (the condition is always satisfied). LTTNG_EVENT_LOGLEVEL_RANGE At least as severe as `event_rule.loglevel`. LTTNG_EVENT_LOGLEVEL_SINGLE Exactly `event_rule.loglevel`. This condition is only meaningful when the tracing domain containing ER is not LTTNG_DOMAIN_KERNEL: it's always satisfied for LTTNG_DOMAIN_KERNEL.
Event payload and context filter	An event E satisfies the event payload and context filter condition of ER if `event_rule` has no filter expression or if its filter expression EXPR evaluates to true when LTTng creates E. This condition is only meaningful when `event_rule.type` is LTTNG_EVENT_TRACEPOINT or LTTNG_EVENT_SYSCALL: it's always satisfied for the other instrumentation point types. Set the event payload and context filter expression of `event_rule` when you call lttng_enable_event_with_exclusions(). Get the event payload and context filter expression of `event_rule` descriptor with lttng_event_get_filter_expression().

Implicit conditions

ER itself is enabled.

A recording event rule is enabled on creation.

See also
lttng_enable_event() – Creates or enables a recording event rule.

lttng_disable_event_ext() – Disables a recording event rule.
The event record channel which contains ER is enabled.

An event record channel is enabled on creation.

See also
lttng_enable_channel() – Creates or enables an event record channel.

lttng_disable_channel() – Disables an event record channel.
The recording session which contains ER is active (started).

A recording session is inactive (stopped) on creation.

See also
lttng_start_tracing() – Starts a recording session.

lttng_stop_tracing() – Stops a recording session.
The process for which LTTng creates E is allowed to record events.

All processes are allowed to record events on recording session creation.

Event record name

When LTTng records an event E, the resulting event record has a name which depends on the instrumentation point type condition of the recording event rule ER which matched E as well as on the tracing domain which contains ER:

Tracing domain	Instrumentation point type	Event record name
LTTNG_DOMAIN_KERNEL or LTTNG_DOMAIN_UST	LTTNG_EVENT_TRACEPOINT	Full name of the tracepoint from which LTTng creates E. Note that the full name of a user space tracepoint is `PROVIDER:NAME`, where `PROVIDER` is the tracepoint provider name and `NAME` is the tracepoint name.
LTTNG_DOMAIN_JUL	LTTNG_EVENT_TRACEPOINT	`lttng_jul:event` Such an event record has a string field `logger_name` which contains the name of the `java.util.logging` logger from which LTTng creates E.
LTTNG_DOMAIN_LOG4J	LTTNG_EVENT_TRACEPOINT	`lttng_log4j:event` Such an event record has a string field `logger_name` which contains the name of the Apache log4j 1.x logger from which LTTng creates E.
LTTNG_DOMAIN_LOG4J2	LTTNG_EVENT_TRACEPOINT	`lttng_log4j2:event` Such an event record has a string field `logger_name` which contains the name of the Apache Log4j 2 logger from which LTTng creates E.
LTTNG_DOMAIN_PYTHON	LTTNG_EVENT_TRACEPOINT	`lttng_python:event` Such an event record has a string field `logger_name` which contains the name of the Python logger from which LTTng creates E.
LTTNG_DOMAIN_KERNEL	LTTNG_EVENT_SYSCALL	Location: Entry `syscall_entry_NAME`, where `NAME` is the name of the system call from which LTTng creates E, without any `sys_` prefix. Exit `syscall_exit_NAME`, where `NAME` is the name of the system call from which LTTng creates E, without any `sys_` prefix.
LTTNG_DOMAIN_KERNEL	LTTNG_EVENT_PROBE or LTTNG_EVENT_USERSPACE_PROBE	The lttng_event::name member of the descriptor you used to create ER with lttng_enable_event_with_exclusions().
LTTNG_DOMAIN_KERNEL	LTTNG_EVENT_FUNCTION	Location: Entry `NAME_entry` Exit `NAME_exit` where `NAME` is the lttng_event::name member of the descriptor you used to create ER with lttng_enable_event_with_exclusions().

Enumeration Type Documentation

◆ lttng_event_type

enum lttng_event_type

Instrumentation point type condition of a recording event rule, or instrumentation point type when lttng_list_tracepoints() or lttng_list_syscalls() creates the lttng_event structure.

Enumerator
LTTNG_EVENT_ALL	Recording event rule Match LTTng kernel tracepoints or the entry and exit of Linux system calls.
LTTNG_EVENT_TRACEPOINT	Recording event rule Match LTTng tracepoints or Java/Python logging statements. Instrumentation point descriptor LTTng tracepoint or Java/Python logging statement.
LTTNG_EVENT_PROBE	Recording event rule Match Linux kprobes.
LTTNG_EVENT_FUNCTION	Recording event rule Match Linux kretprobes.
LTTNG_EVENT_SYSCALL	Recording event rule Match the entry and exit of Linux system calls. Instrumentation point descriptor Linux system call.
LTTNG_EVENT_USERSPACE_PROBE	Recording event rule Match Linux user space probes.

◆ lttng_loglevel

enum lttng_loglevel

Value of the instrumentation point log level condition of an LTTng user space tracepoint recording event rule descriptor.

See also: lttng_loglevel_type – Operand of the log level condition of a recording event rule.

Enumerator
LTTNG_LOGLEVEL_EMERG	System is unusable.
LTTNG_LOGLEVEL_ALERT	Action must be taken immediately.
LTTNG_LOGLEVEL_CRIT	Critical conditions.
LTTNG_LOGLEVEL_ERR	Error conditions.
LTTNG_LOGLEVEL_WARNING	Warning conditions.
LTTNG_LOGLEVEL_NOTICE	Normal, but significant, condition.
LTTNG_LOGLEVEL_INFO	Informational message.
LTTNG_LOGLEVEL_DEBUG_SYSTEM	Debug information with system-level scope (set of programs).
LTTNG_LOGLEVEL_DEBUG_PROGRAM	Debug information with program-level scope (set of processes).
LTTNG_LOGLEVEL_DEBUG_PROCESS	Debug information with process-level scope (set of modules).
LTTNG_LOGLEVEL_DEBUG_MODULE	Debug information with module (executable/library) scope (set of units).
LTTNG_LOGLEVEL_DEBUG_UNIT	Debug information with compilation unit scope (set of functions).
LTTNG_LOGLEVEL_DEBUG_FUNCTION	Debug information with function-level scope.
LTTNG_LOGLEVEL_DEBUG_LINE	Debug information with line-level scope.
LTTNG_LOGLEVEL_DEBUG	Debug-level message.

◆ lttng_loglevel_jul

enum lttng_loglevel_jul

Value of the instrumentation point log level condition of a java.util.logging recording event rule.

See also: lttng_loglevel_type – Operand of the log level condition of a recording event rule.

Enumerator
LTTNG_LOGLEVEL_JUL_OFF	Logging turned off.
LTTNG_LOGLEVEL_JUL_SEVERE	Serious failure.
LTTNG_LOGLEVEL_JUL_WARNING	Potential problem.
LTTNG_LOGLEVEL_JUL_INFO	Informational messages.
LTTNG_LOGLEVEL_JUL_CONFIG	Static configuration messages.
LTTNG_LOGLEVEL_JUL_FINE	Tracing information.
LTTNG_LOGLEVEL_JUL_FINER	Fairly detailed tracing message.
LTTNG_LOGLEVEL_JUL_FINEST	Highly detailed tracing message.
LTTNG_LOGLEVEL_JUL_ALL	All messages.

◆ lttng_loglevel_log4j

enum lttng_loglevel_log4j

Value of the instrumentation point log level condition of an Apache log4j 1.x recording event rule.

See also: lttng_loglevel_type – Operand of the log level condition of a recording event rule.

Enumerator
LTTNG_LOGLEVEL_LOG4J_OFF	Logging turned off.
LTTNG_LOGLEVEL_LOG4J_FATAL	Very severe error events that will presumably lead the application to abort.
LTTNG_LOGLEVEL_LOG4J_ERROR	Error events that might still allow the application to continue running.
LTTNG_LOGLEVEL_LOG4J_WARN	Potentially harmful situations.
LTTNG_LOGLEVEL_LOG4J_INFO	Informational messages that highlight the progress of the application at coarse-grained level.
LTTNG_LOGLEVEL_LOG4J_DEBUG	Fine-grained informational events that are most useful to debug an application.
LTTNG_LOGLEVEL_LOG4J_TRACE	Finer-grained informational events than the LTTNG_LOGLEVEL_LOG4J_DEBUG level.
LTTNG_LOGLEVEL_LOG4J_ALL	All levels, including custom levels.

◆ lttng_loglevel_log4j2

enum lttng_loglevel_log4j2

Value of the instrumentation point log level condition of a Apache Log4j 2 recording event rule.

See also: lttng_loglevel_type – Operand of the log level condition of a recording event rule.

Enumerator
LTTNG_LOGLEVEL_LOG4J2_OFF	Logging turned off.
LTTNG_LOGLEVEL_LOG4J2_FATAL	Very severe error events that will presumably lead the application to abort.
LTTNG_LOGLEVEL_LOG4J2_ERROR	Error events that might still allow the application to continue running.
LTTNG_LOGLEVEL_LOG4J2_WARN	Potentially harmful situations.
LTTNG_LOGLEVEL_LOG4J2_INFO	Informational messages that highlight the progress of the application at coarse-grained level.
LTTNG_LOGLEVEL_LOG4J2_DEBUG	Fine-grained informational events that are most useful to debug an application.
LTTNG_LOGLEVEL_LOG4J2_TRACE	Finer-grained informational events than the LTTNG_LOGLEVEL_LOG4J2_DEBUG level.
LTTNG_LOGLEVEL_LOG4J2_ALL	All levels, including custom levels.

◆ lttng_loglevel_python

enum lttng_loglevel_python

Value of the instrumentation point log level condition of a Python recording event rule.

See also: lttng_loglevel_type – Operand of the log level condition of a recording event rule.

Enumerator
LTTNG_LOGLEVEL_PYTHON_CRITICAL	Critical.
LTTNG_LOGLEVEL_PYTHON_ERROR	Error.
LTTNG_LOGLEVEL_PYTHON_WARNING	Warning.
LTTNG_LOGLEVEL_PYTHON_INFO	Information.
LTTNG_LOGLEVEL_PYTHON_DEBUG	Debugging.
LTTNG_LOGLEVEL_PYTHON_NOTSET	Logging turned off.

◆ lttng_loglevel_type

enum lttng_loglevel_type

Operand of the instrumentation point log level condition of a recording event rule.

In the enumerator descriptions below, consider that LL is the log level value of the condition, that is, the value of the lttng_event::loglevel member when the lttng_event::loglevel_type member is the described enumerator.

Depending on the tracing domain of the recording event rule, LL is one of the enumerators of lttng_loglevel, lttng_loglevel_jul, lttng_loglevel_log4j, lttng_loglevel_log4j2, or lttng_loglevel_python.

Enumerator
LTTNG_EVENT_LOGLEVEL_ALL	Match events regardless of their log level.
LTTNG_EVENT_LOGLEVEL_RANGE	Match events with a log level that's at least as severe as LL.
LTTNG_EVENT_LOGLEVEL_SINGLE	Match events with a log level that's exacty LL.

Function Documentation

◆ lttng_disable_event()

int lttng_disable_event	(	struct lttng_handle *	handle,
		const char *	event_rule_name,
		const char *	channel_name
	)

extern

Alias of lttng_disable_event_ext() which creates a temporary recording event rule descriptor, settings its lttng_event::name member to event_rule_name if not NULL and its lttng_event::type member to LTTNG_EVENT_ALL.

This function is equivalent to:

struct lttng_event event_rule = { 0 };
 
event_rule.type = LTTNG_EVENT_ALL;
 
if (event_name) {
    strcpy(event_rule.name, event_name);
}
 
event_rule.loglevel = -1;
return lttng_disable_event_ext(handle, &event_rule, channel_name, NULL);

Parameters

[in]	handle	See lttng_disable_event_ext().
[in]	event_rule_name	What to use as the lttng_event::name member of the created temporary event rule descriptor passed to lttng_disable_event_ext().
[in]	channel_name	See lttng_disable_event_ext().

Returns: See lttng_disable_event_ext().

Precondition: See lttng_disable_event_ext().

◆ lttng_disable_event_ext()

int lttng_disable_event_ext	(	struct lttng_handle *	handle,
		struct lttng_event *	event_rule,
		const char *	channel_name,
		const char *	filter_expr
	)

extern

Disables recording event rules by instrumentation point type and event name condition within the event record channel named channel_name (or within a default event record channel if NULL) within the recording session handle handle.

Depending on event_rule->name, this function:

Not empty

Depending on event_rule->type:

LTTNG_EVENT_ALL

Disables all the recording event rules of which the event name pattern is exactly event_rule->name within the selected event record channel.

Otherwise

Disables all the recording event rules of which the instrumentation point type is event_rule->type and the event name pattern is exactly event_rule->name within the selected event record channel.

Only supported when handle->domain.type is LTTNG_DOMAIN_KERNEL.

Empty

Depending on event_rule->type:

LTTNG_EVENT_ALL

Disables all the recording event rules within the selected event record channel.

Otherwise

Disables all the recording event rules of which the instrumentation point type is event_rule->type within the selected event record channel.

Only supported when handle->domain.type is LTTNG_DOMAIN_KERNEL.

This function ignores all the other condition properties of event_rule.

To use this function, create a temporary, zeroed recording event rule descriptor, setting only:

Optional, and only if handle->domain.type is LTTNG_DOMAIN_KERNEL: its lttng_event::type member.
Optional: its lttng_event::name member
Its lttng_event::loglevel member to -1.

For example:

struct lttng_event event_rule = { 0 };
 
event_rule.type = LTTNG_EVENT_SYSCALL;
strcpy(event_rule.name, "open*");
event_rule.loglevel = -1;

Parameters

[in]	handle	Recording session handle which contains the name of the recording session and the summary of the tracing domain which own the selected event record channel.
[in]	event_rule	Recording event rule descriptor which contains the instrumentation point type and event name conditions to consider to disable recording event rules within the selected event record channel.
[in]	channel_name	Name of the event record channel, within `handle`, to select (that is, containing the recording event rules to disable). If `NULL`, then this function uses `channel0`.
[in]	filter_expr	Unused: must be `NULL`.

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.
event_rule is not NULL.
If handle->domain.type is not LTTNG_DOMAIN_KERNEL, then event_rule->type is LTTNG_EVENT_ALL.
If not LTTNG_EVENT_ALL, then event_rule->type is the instrumentation point type of at least one Linux kernel recording event rule within the selected event record channel.
If not empty, then event_rule->name is the exact event name pattern of at least one recording event rule within the selected event record channel.
The recording event rules to disable are enabled.
If not NULL, then channel_name names an existing event record channel within the recording session and tracing domain of handle.
If channel_name is NULL, then the event record channel named channel0 exists within the recording session and tracing domain of handle.

See also: lttng_disable_event() – Alias which calls this function with event_rule->type set to LTTNG_EVENT_ALL.; lttng_enable_event_with_exclusions() – Creates or enables a recording event rule.

◆ lttng_enable_event()

int lttng_enable_event	(	struct lttng_handle *	handle,
		struct lttng_event *	event_rule,
		const char *	channel_name
	)

extern

Alias of lttng_enable_event_with_exclusions() which passes the event payload and context filter expression of event_rule as the filter_expr parameter and the event name exclusion patterns of event_rule as the event_name_exclusion_count and event_name_exclusions parameters.

This function is equivalent to:

int ret;
int i;
char **event_name_exclusions = NULL;
const char *filter_expr = NULL;
const int event_name_exclusion_count = lttng_event_get_exclusion_name_count(event_rule);
 
assert(event_name_exclusion_count >= 0);
 
if (event_name_exclusion_count > 0) {
    event_name_exclusions = calloc(event_name_exclusion_count,
                                   sizeof(*event_name_exclusions));
    assert(event_name_exclusions);
 
    for (i = 0; i < event_name_exclusion_count; i++) {
        const char *event_name_exclusion;
 
        ret = lttng_event_get_exclusion_name(event_rule, (size_t) i,
                                             &event_name_exclusion);
        assert(ret == 0);
        event_name_exclusions[i] = (char *) event_name_exclusion;
    }
}
 
ret = lttng_event_get_filter_expression(event_rule, &filter_expr);
assert(ret == 0);
ret = lttng_enable_event_with_exclusions(handle, event_rule, channel_name,
                                         filter_expr,
                                         event_name_exclusion_count,
                                         event_name_exclusions);
free(event_name_exclusions);
return ret;

Parameters

[in]	handle	See lttng_enable_event_with_exclusions().
[in]	event_rule	See lttng_enable_event_with_exclusions().
[in]	channel_name	See lttng_enable_event_with_exclusions().

Returns: See lttng_enable_event_with_exclusions().

Precondition: See lttng_enable_event_with_exclusions().

◆ lttng_enable_event_with_exclusions()

int lttng_enable_event_with_exclusions	(	struct lttng_handle *	handle,
		struct lttng_event *	event_rule,
		const char *	channel_name,
		const char *	filter_expr,
		int	event_name_exclusion_count,
		char **	event_name_exclusions
	)

extern

Creates or enables a recording event rule described by event_rule, having the event payload and context filter expression filter_expr and the event name exclusion patterns event_name_exclusions, within the event record channel named channel_name (or within a default event record channel if NULL) within the recording session handle handle.

This function, depending on the instrumentation point type, event name, and log level conditions of event_rule, as well as on filter_expr and event_name_exclusions:

The conditions and parameters describe an existing recording event rule within the selected event record channel

Enables the existing recording event rule.

Otherwise

Creates and enables a new recording event rule within the selected event record channel.

If event_rule->type is LTTNG_EVENT_ALL and handle->domain.type is LTTNG_DOMAIN_KERNEL, then this function actually creates or enables two recording event rules: one with the LTTNG_EVENT_TRACEPOINT type, and one with the LTTNG_EVENT_SYSCALL type.

Parameters

[in]	handle	Recording session handle which contains the name of the recording session and the summary of the tracing domain which own the selected event record channel.
[in]	event_rule	Descriptor of the recording event rule to create or enable. This function: Ignores any event payload and context filter expression within `event_rule`: it always uses `filter_expr`. Ignores any event name exclusion patterns within `event_rule`: it always uses `event_name_exclusions`.
[in]	channel_name	Name of the event record channel, within `handle`, to select (that is, containing the recording event rule to create or enable). If `NULL`, then this function uses `channel0`. If no event record channel named `channel0` within `handle` exists, then LTTng creates a new, default event record channel named as such and selects it before it creates the recording event rule described by `event_rule`.
[in]	filter_expr	Event payload and context filter expression of the recording event rule to create or enable (copied). If `NULL`, the created or enabled recording event rule has no event payload and context filter expression. This parameter, even when `NULL`, overrides any existing event payload and context filter expression within `event_rule`.
[in]	event_name_exclusion_count	Number of items in `event_name_exclusions`.
[in]	event_name_exclusions	Event name exclusion patterns of the recording event rule to create or enable. This function copies the strings of this array. `event_name_exclusion_count` indicates the size of this array, which may be `NULL` if `event_name_exclusion_count` is 0. This parameter, even when `NULL` or empty, overrides any existing event name exclusion patterns within `event_rule`.

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.
event_rule is not NULL.
event_rule is valid.
If handle->domain.type is not LTTNG_DOMAIN_KERNEL, then event_rule->type is LTTNG_EVENT_TRACEPOINT.
If handle->domain.type is not LTTNG_DOMAIN_UST, then event_name_exclusion_count is 0.
If this function must enable an existing recording event rule, then the recording event rule to enable is disabled.
If not NULL, channel_name names an existing event record channel within the recording session and tracing domain of handle.
If channel_name is NULL, then handle contains either no event record channels or a default event record channel named channel0.
If not NULL, filter_expr is a valid event payload and context filter expression.
event_name_exclusion_count ≥ 0.

See also: lttng_enable_event() – Alias which calls this function with the event payload and context filter expression and event name exclusion patterns of the recording event rule descriptor.; lttng_enable_event_with_filter() – Alias which calls this function with the event name exclusion patterns of the recording event rule descriptor.; lttng_disable_event_ext() – Disables a recording event rule.

◆ lttng_enable_event_with_filter()

int lttng_enable_event_with_filter	(	struct lttng_handle *	handle,
		struct lttng_event *	event_rule,
		const char *	channel_name,
		const char *	filter_expr
	)

extern

Alias of lttng_enable_event_with_exclusions() which passes the the event name exclusion patterns of event_rule as the event_name_exclusion_count and event_name_exclusions parameters.

This function is equivalent to:

int ret;
int i;
char **event_name_exclusions = NULL;
const char *filter_expr = NULL;
const int event_name_exclusion_count = lttng_event_get_exclusion_name_count(event_rule);
 
assert(event_name_exclusion_count >= 0);
 
if (event_name_exclusion_count > 0) {
    event_name_exclusions = calloc(event_name_exclusion_count,
                                   sizeof(*event_name_exclusions));
    assert(event_name_exclusions);
 
    for (i = 0; i < event_name_exclusion_count; i++) {
        const char *event_name_exclusion;
 
        ret = lttng_event_get_exclusion_name(event_rule, (size_t) i,
                                             &event_name_exclusion);
        assert(ret == 0);
        event_name_exclusions[i] = (char *) event_name_exclusion;
    }
}
 
ret = lttng_enable_event_with_exclusions(handle, event_rule, channel_name,
                                         filter_expr,
                                         event_name_exclusion_count,
                                         event_name_exclusions);
free(event_name_exclusions);
return ret;

Parameters

[in]	handle	See lttng_enable_event_with_exclusions().
[in]	event_rule	See lttng_enable_event_with_exclusions().
[in]	channel_name	See lttng_enable_event_with_exclusions().
[in]	filter_expr	See lttng_enable_event_with_exclusions().

Returns: See lttng_enable_event_with_exclusions().

Precondition: See lttng_enable_event_with_exclusions().

◆ lttng_event_create()

struct lttng_event * lttng_event_create ( void )

extern

Creates and returns an empty recording event rule descriptor.

After you create a recording event rule descriptor with this function, you can modify its properties and call lttng_enable_event_with_exclusions() to create and enable a recording event rule.

Returns

New recording event rule descriptor.

Destroy the returned recording event rule descriptor with lttng_event_destroy().

See also: lttng_event_destroy() – Destroys a recording event rule descriptor.

◆ lttng_event_destroy()

void lttng_event_destroy ( struct lttng_event * event_rule )

extern

Destroys the recording event rule descriptor event_rule.

Note: This function doesn't destroy the recording event rule which event_rule describes: you can't destroy a recording event rule.

Parameters

[in]

event_rule

Recording event rule descriptor to destroy.

May be NULL.

Precondition

If not NULL, event_rule was created with lttng_event_create().

See also: lttng_event_create() – Creates an empty recording event rule descriptor.

◆ lttng_event_get_exclusion_name()

int lttng_event_get_exclusion_name	(	const struct lttng_event *	event_rule,
		size_t	index,
		const char **	event_name_exclusion
	)

extern

Sets *event_name_exclusion to the event name exclusion pattern at index index of the recording event rule described by event_rule.

Parameters

[in] event_rule Descriptor of the recording event rule of which to get the event name exclusion pattern at index index.

[in] index Index of the event name exclusion pattern to get from event_rule.

[out]

event_name_exclusion

On success, this function sets *event_name_exclusion to the event name exclusion pattern at index index of event_rule.

*event_name_exclusion remains valis as long as event_rule exists and you don't modify it.

Returns

0

Success.

-LTTNG_ERR_INVALID (negative)

-LTTNG_ERR_OVERFLOW (negative)

Unsatisfied precondition.

Precondition

event_rule is not NULL.
index is less than the number of event name exclusion patterns (as returned by lttng_event_get_exclusion_name_count()) of event_rule.
event_name_exclusion is not NULL.

See also: lttng_event_get_exclusion_name_count() – Returns the number of event name exclusion patterns of a recording event rule.

◆ lttng_event_get_exclusion_name_count()

int lttng_event_get_exclusion_name_count ( const struct lttng_event * event_rule )

extern

Returns the number of event name exclusion patterns of the recording event rule described by event_rule.

Parameters

[in] event_rule Descriptor of the recording event rule of which to get the number of event name exclusion patterns.

Returns: Number of event name exclusion patterns of event_rule, or a negative lttng_error_code enumerator otherwise.

Precondition

event_rule is not NULL.

See also: lttng_event_get_exclusion_name() – Returns an event name exclusion pattern by index of a recording event rule.; lttng_event::exclusion – Indicates whether or not a recording event rule has event name exclusion patterns.

◆ lttng_event_get_filter_expression()

int lttng_event_get_filter_expression	(	const struct lttng_event *	event_rule,
		const char **	filter_expr
	)

extern

Sets *filter_expr to the event payload and context filter expression of the recording event rule described by event_rule.

Parameters

[in] event_rule Descriptor of the recording event rule of which to get the event payload and context filter expression.

[out]

filter_expr

On success, this function sets *filter_expr to:

If event_rule has an event payload and context filter expression

The event payload and context filter expression of event_rule.

*filter_expr remains valid as long as event_rule exists and you don't modify it.

Otherwise

NULL

Returns

0

Success.

-LTTNG_ERR_INVALID (negative)

Unsatisfied precondition.

Precondition

event_rule is not NULL.
filter_expr is not NULL.

See also: lttng_event::filter – Indicates whether or not a recording event rule has an event payload and context filter.

◆ lttng_event_get_userspace_probe_location()

const struct lttng_userspace_probe_location * lttng_event_get_userspace_probe_location ( const struct lttng_event * event_rule )

extern

Returns the Linux user space probe location of the recording event rule described by event_rule.

Parameters

[in] event_rule Descriptor of the recording event rule of which to get the Linux user space probe location.

Returns

Linux user space probe location of the recording event rule described by event_rule, or NULL if none.

The returned location remains valid as long as event_rule exists and you don't modify it.

Precondition

event_rule is not NULL.
event_rule->type (see lttng_event::type) is LTTNG_EVENT_USERSPACE_PROBE.

See also: lttng_event_set_userspace_probe_location() – Sets the Linux user space probe location of a recording event rule.; Instrumentation point type condition.

◆ lttng_event_set_userspace_probe_location()

int lttng_event_set_userspace_probe_location	(	struct lttng_event *	event_rule,
		struct lttng_userspace_probe_location *	location
	)

extern

Sets the Linux user space probe location of the recording event rule described by event_rule to location.

Parameters

[in]	event_rule	Descriptor of the recording event rule of which to set the Linux user space probe location to `location`.
[in]	location	New Linux user space probe location of `event_rule`.

Returns

0

Success.

-LTTNG_ERR_INVALID (negative)

Unsatisfied precondition.

Precondition

event_rule is not NULL.
event_rule was created with lttng_event_create().
event_rule->type (see lttng_event::type) is LTTNG_EVENT_USERSPACE_PROBE.
location is not NULL.

Postcondition: On success, *location is invalid (its ownership is transfered to event_rule).

See also: lttng_event_get_userspace_probe_location() – Returns the Linux user space probe location of a recording event rule.; Instrumentation point type condition.

Data Structures

Enumerations

Functions

Detailed Description

Concepts

Operations

Recording event rule conditions

Event record name

Enumeration Type Documentation

◆ lttng_event_type

◆ lttng_loglevel

◆ lttng_loglevel_jul

◆ lttng_loglevel_log4j

◆ lttng_loglevel_log4j2

◆ lttng_loglevel_python

◆ lttng_loglevel_type

Function Documentation

◆ lttng_disable_event()

◆ lttng_disable_event_ext()

◆ lttng_enable_event()

◆ lttng_enable_event_with_exclusions()

◆ lttng_enable_event_with_filter()

◆ lttng_event_create()

◆ lttng_event_destroy()

◆ lttng_event_get_exclusion_name()

◆ lttng_event_get_exclusion_name_count()

◆ lttng_event_get_filter_expression()

◆ lttng_event_get_userspace_probe_location()

◆ lttng_event_set_userspace_probe_location()