Event rule API

Collaboration diagram for Event rule API:

Modules
	Log level rule API
	LTTng kernel tracepoint event rule API
	Linux kernel system call event rule API
	Linux kprobe event rule API
	Linux user space probe event rule API
	LTTng user space tracepoint event rule API
	JUL event rule API
	Apache log4j 1.x event rule API
	Apache Log4j 2 event rule API
	Python logging event rule API

Data Structures
struct	lttng_event_rule
	Event rule (opaque type). More...

Enumerations
enum	lttng_event_rule_status {   LTTNG_EVENT_RULE_STATUS_OK , LTTNG_EVENT_RULE_STATUS_ERROR , LTTNG_EVENT_RULE_STATUS_UNKNOWN , LTTNG_EVENT_RULE_STATUS_INVALID ,   LTTNG_EVENT_RULE_STATUS_UNSET , LTTNG_EVENT_RULE_STATUS_UNSUPPORTED }
	Return type of event rule API functions. More...
enum	lttng_event_rule_type {   LTTNG_EVENT_RULE_TYPE_KERNEL_TRACEPOINT , LTTNG_EVENT_RULE_TYPE_KERNEL_SYSCALL , LTTNG_EVENT_RULE_TYPE_KERNEL_KPROBE , LTTNG_EVENT_RULE_TYPE_KERNEL_UPROBE ,   LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT , LTTNG_EVENT_RULE_TYPE_JUL_LOGGING , LTTNG_EVENT_RULE_TYPE_LOG4J_LOGGING , LTTNG_EVENT_RULE_TYPE_LOG4J2_LOGGING ,   LTTNG_EVENT_RULE_TYPE_PYTHON_LOGGING , LTTNG_EVENT_RULE_TYPE_UNKNOWN }
	Event rule type. More...

Functions
void	lttng_event_rule_destroy (struct lttng_event_rule *rule)
	Destroys the event rule rule.
enum lttng_event_rule_type	lttng_event_rule_get_type (const struct lttng_event_rule *rule)
	Returns the type of the event rule rule.

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.

An event has a name and fields.

When LTTng creates an event E, an 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 an event rule matches an event, LTTng emits the event, therefore attempting to execute an action.

Attention

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

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.

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 event rule, a few current process attribute checks.

The only purpose of an event rule object is to create an “event rule matches” trigger condition from it. When the event rule of the trigger condition matches an event, LTTng can execute a user-defined action such as sending an LTTng notification, starting a recording session, and more.

Get the type of an event rule with lttng_event_rule_get_type().

Destroy an event rule with lttng_event_rule_destroy().

See also

• The “INSTRUMENTATION POINT, EVENT RULE, AND EVENT” section of lttng-concepts(7).
• lttng-event-rule(7).

Event rule conditions

For LTTng to emit an event E, E must satisfy all the conditions of an event rule ER.

You set the following conditions when or after you create ER with one of the creation functions listed below:

Condition	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 type of ER: LTTNG_EVENT_RULE_TYPE_KERNEL_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. Create ER with lttng_event_rule_kernel_tracepoint_create(). See also lttng_list_tracepoints() LTTNG_EVENT_RULE_TYPE_KERNEL_SYSCALL The entry, exit, or entry and exit of a Linux kernel system call. Create ER with lttng_event_rule_kernel_syscall_create(). See also lttng_list_syscalls() LTTNG_EVENT_RULE_TYPE_KERNEL_KPROBE A Linux kprobe, that is, a single probe dynamically placed in the compiled kernel code. You indicate the location of the Linux kprobe to instrument when you create ER with lttng_event_rule_kernel_kprobe_create(). Although lttng_event_rule_kernel_kprobe_create() sets an initial event name from the kprobe location, you can override it with lttng_event_rule_kernel_kprobe_set_event_name(). The payload of a Linux kprobe event is empty. LTTNG_EVENT_RULE_TYPE_KERNEL_UPROBE 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. You indicate the location of the Linux user space probe to instrument when you create ER with lttng_event_rule_kernel_uprobe_create(). Although lttng_event_rule_kernel_uprobe_create() sets an initial event name from the user space probe location, you can override it with lttng_event_rule_kernel_uprobe_set_event_name(). The payload of a Linux user space probe event is empty. LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT 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. Create ER with lttng_event_rule_user_tracepoint_create(). See also lttng_list_tracepoints() LTTNG_EVENT_RULE_TYPE_JUL_LOGGING A <code>java.util.logging</code> logging statement. Create ER with lttng_event_rule_jul_logging_create(). See also lttng_list_tracepoints() LTTNG_EVENT_RULE_TYPE_LOG4J_LOGGING An Apache log4j 1.x logging statement. Create ER with lttng_event_rule_log4j_logging_create(). See also lttng_list_tracepoints() LTTNG_EVENT_RULE_TYPE_LOG4J2_LOGGING An Apache Log4j 2 logging statement. Create ER with lttng_event_rule_log4j2_logging_create(). See also lttng_list_tracepoints() LTTNG_EVENT_RULE_TYPE_PYTHON_LOGGING A Python logging statement. Create ER with lttng_event_rule_python_logging_create(). See also lttng_list_tracepoints()
Event name	An event E satisfies the event name condition of ER if the two following statements are true: The event name pattern of ER matches, depending on the type of ER (see Instrumentation point type above): LTTNG_EVENT_RULE_TYPE_KERNEL_TRACEPOINT LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT LTTNG_EVENT_RULE_TYPE_JUL_LOGGING LTTNG_EVENT_RULE_TYPE_LOG4J_LOGGING LTTNG_EVENT_RULE_TYPE_LOG4J2_LOGGING LTTNG_EVENT_RULE_TYPE_PYTHON_LOGGING The full name of the LTTng tracepoint or Java/Python logger from which LTTng creates E. Note that the full name of an LTTng user space tracepoint is PROVIDER:NAME, where PROVIDER is the tracepoint provider name and NAME is the tracepoint name. LTTNG_EVENT_RULE_TYPE_KERNEL_SYSCALL The name of the system call, without any sys_ prefix, from which LTTng creates E. When you create ER, the initial event name pattern is equivalent to * (any event name). Set the event name pattern of ER with one of: lttng_event_rule_kernel_tracepoint_set_name_pattern() lttng_event_rule_kernel_syscall_set_name_pattern() lttng_event_rule_user_tracepoint_set_name_pattern() lttng_event_rule_jul_logging_set_name_pattern() lttng_event_rule_log4j_logging_set_name_pattern() lttng_event_rule_log4j2_logging_set_name_pattern() lttng_event_rule_python_logging_set_name_pattern() Get the event name pattern of ER with one of: lttng_event_rule_kernel_tracepoint_get_name_pattern() lttng_event_rule_kernel_syscall_get_name_pattern() lttng_event_rule_user_tracepoint_get_name_pattern() lttng_event_rule_jul_logging_get_name_pattern() lttng_event_rule_log4j_logging_get_name_pattern() lttng_event_rule_log4j2_logging_get_name_pattern() lttng_event_rule_python_logging_get_name_pattern() See also Event name. If the type of ER is LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT, then none of the event name exclusion patterns of ER matches the full name of the user space tracepoint from which LTTng creates E. When you create ER, the initial event name exclusion pattern set is empty (no exclusions). Add an event name exclusion pattern to ER with lttng_event_rule_user_tracepoint_add_name_pattern_exclusion(). Get an event name exclusion pattern of ER with lttng_event_rule_user_tracepoint_get_name_pattern_exclusion_at_index(). This condition isn't meaningful (always satisfied) if the type of ER is LTTNG_EVENT_RULE_TYPE_KERNEL_KPROBE or LTTNG_EVENT_RULE_TYPE_KERNEL_UPROBE. In all cases, the event name and event name exclusion patterns 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 the log level LL of the LTTng user space tracepoint or logging statement from which LTTng creates E satisfies the log level rule LLR of ER. An event E satisfies this condition if LL is, depending on the type of LLR: LTTNG_LOG_LEVEL_RULE_TYPE_AT_LEAST_AS_SEVERE_AS At least as severe as what lttng_log_level_rule_at_least_as_severe_as_get_level() returns with LLR. LTTNG_LOG_LEVEL_RULE_TYPE_EXACTLY Exactly what lttng_log_level_rule_exactly_get_level() returns with LLR. If ER has no log level rule, then this condition is always satisfied. This condition isn't meaningful (always satisfied) if the type of ER is one of: LTTNG_EVENT_RULE_TYPE_KERNEL_TRACEPOINT LTTNG_EVENT_RULE_TYPE_KERNEL_SYSCALL LTTNG_EVENT_RULE_TYPE_KERNEL_KPROBE LTTNG_EVENT_RULE_TYPE_KERNEL_UPROBE When you create ER, there's no initial log level rule (this condition is always satisfied). Set the log level rule of ER with one of: lttng_event_rule_user_tracepoint_set_log_level_rule() lttng_event_rule_jul_logging_set_log_level_rule() lttng_event_rule_log4j_logging_set_log_level_rule() lttng_event_rule_log4j2_logging_set_log_level_rule() lttng_event_rule_python_logging_set_log_level_rule() Get the log level rule of ER with one of: lttng_event_rule_user_tracepoint_get_log_level_rule() lttng_event_rule_jul_logging_get_log_level_rule() lttng_event_rule_log4j_logging_get_log_level_rule() lttng_event_rule_log4j2_logging_get_log_level_rule() lttng_event_rule_python_logging_get_log_level_rule()
Event payload and context filter	An event E satisfies the event payload and context filter condition of ER if ER has no filter expression or if its filter expression EXPR evaluates to true when LTTng creates E. This condition isn't meaningful (always satisfied) if the type of ER is LTTNG_EVENT_RULE_TYPE_KERNEL_KPROBE or LTTNG_EVENT_RULE_TYPE_KERNEL_UPROBE. When you create ER, the initial event payload and context filter is equivalent to 1 (no filter: the condition is always satisfied). Set the event payload and context filter expression of ER with one of: lttng_event_rule_kernel_tracepoint_set_filter() lttng_event_rule_kernel_syscall_set_filter() lttng_event_rule_user_tracepoint_set_filter() lttng_event_rule_jul_logging_set_filter() lttng_event_rule_log4j_logging_set_filter() lttng_event_rule_log4j2_logging_set_filter() lttng_event_rule_python_logging_set_filter() Get the event payload and context filter expression of ER with one of: lttng_event_rule_kernel_tracepoint_get_filter() lttng_event_rule_kernel_syscall_get_filter() lttng_event_rule_user_tracepoint_get_filter() lttng_event_rule_jul_logging_get_filter() lttng_event_rule_log4j_logging_get_filter() lttng_event_rule_log4j2_logging_get_filter() lttng_event_rule_python_logging_get_filter()

Event name

When LTTng emits an event E, the resulting event has a name which depends on the instrumentation point type condition of the event rule ER which matched E:

Instrumentation point type	Event name
LTTNG_EVENT_RULE_TYPE_KERNEL_TRACEPOINT or LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT	Full name of the tracepoint from which LTTng creates E. Note that the full name of an LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT event rule is PROVIDER:NAME, where PROVIDER is the tracepoint provider name and NAME is the tracepoint name.
LTTNG_EVENT_RULE_TYPE_KERNEL_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_EVENT_RULE_TYPE_KERNEL_KPROBE or LTTNG_EVENT_RULE_TYPE_KERNEL_UPROBE	Location: Entry NAME_entry Exit NAME_exit where NAME is the event name of ER. Both lttng_event_rule_kernel_kprobe_create() and lttng_event_rule_kernel_uprobe_create() set an initial event name from the probe location. Override the event name of ER with lttng_event_rule_kernel_kprobe_set_event_name() or lttng_event_rule_kernel_uprobe_set_event_name(). Get the event name of ER with lttng_event_rule_kernel_kprobe_get_event_name() or lttng_event_rule_kernel_uprobe_get_event_name().
LTTNG_EVENT_RULE_TYPE_JUL_LOGGING	lttng_jul:event Such an event has a string field logger_name which contains the name of the java.util.logging logger from which LTTng creates E.
LTTNG_EVENT_RULE_TYPE_LOG4J_LOGGING	lttng_log4j:event Such an event has a string field logger_name which contains the name of the Apache log4j 1.x logger from which LTTng creates E.
LTTNG_EVENT_RULE_TYPE_LOG4J2_LOGGING	lttng_log4j2:event Such an event has a string field logger_name which contains the name of the Apache Log4j 2 logger from which LTTng creates E.
LTTNG_EVENT_RULE_TYPE_PYTHON_LOGGING	lttng_python:event Such an event has a string field logger_name which contains the name of the Python logger from which LTTng creates E.

Enumeration Type Documentation

lttng_event_rule_status

enum lttng_event_rule_status

Return type of event rule API functions.

Enumerator
LTTNG_EVENT_RULE_STATUS_OK	Success.
LTTNG_EVENT_RULE_STATUS_ERROR	Error.
LTTNG_EVENT_RULE_STATUS_INVALID	Unsatisfied precondition.
LTTNG_EVENT_RULE_STATUS_UNSET	Not set.
LTTNG_EVENT_RULE_STATUS_UNSUPPORTED	Unsupported.

lttng_event_rule_type

enum lttng_event_rule_type

Event rule type.

See the instrumentation point type condition.

Get the type of an event rule with lttng_event_rule_get_type().

Enumerator
LTTNG_EVENT_RULE_TYPE_KERNEL_TRACEPOINT	Match LTTng kernel tracepoints.
LTTNG_EVENT_RULE_TYPE_KERNEL_SYSCALL	Match Linux kernel system calls.
LTTNG_EVENT_RULE_TYPE_KERNEL_KPROBE	Match Linux kprobes.
LTTNG_EVENT_RULE_TYPE_KERNEL_UPROBE	Match Linux user space probes.
LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT	Match LTTng user space tracepoints.
LTTNG_EVENT_RULE_TYPE_JUL_LOGGING	Match java.util.logging (JUL) logging statements.
LTTNG_EVENT_RULE_TYPE_LOG4J_LOGGING	Match Apache log4j 1.x logging statements.
LTTNG_EVENT_RULE_TYPE_LOG4J2_LOGGING	Match Apache Log4j 2 logging statements.
LTTNG_EVENT_RULE_TYPE_PYTHON_LOGGING	Match Python logging statements.
LTTNG_EVENT_RULE_TYPE_UNKNOWN	Unknown (error).

Function Documentation

lttng_event_rule_destroy()

void lttng_event_rule_destroy ( struct lttng_event_rule *  rule )

extern

Destroys the event rule rule.

Parameters

[in]

rule

Event rule to destroy. May be NULL.

lttng_event_rule_get_type()

enum lttng_event_rule_type lttng_event_rule_get_type ( const struct lttng_event_rule *  rule )

extern

Returns the type of the event rule rule.

Parameters

[in]

rule

Event rule of which to get the type.

Returns

Type of rule.

Precondition

• rule is not NULL.