lttng_event Struct Reference

Recording event rule descriptor. More...

#include <event.h>

Collaboration diagram for lttng_event:

Data Fields
union lttng_event_attr_u	attr
int32_t	enabled
unsigned char	exclusion
unsigned char	filter
enum lttng_event_flag	flags
int	loglevel
enum lttng_loglevel_type	loglevel_type
char	name [LTTNG_SYMBOL_NAME_LEN]
pid_t	pid
enum lttng_event_type	type

Detailed Description

Recording event rule descriptor.

Such a structure describes a recording event rule. More specifically, it describes the conditions of a recording event rule.

lttng_list_events() sets a pointer to an array of all the recording event rule descriptors of a given channel.

Note

lttng_list_tracepoints() and lttng_list_syscalls() also set a pointer to an array of instances of this structure. In this context, the lttng_event structure is named "instrumentation point descriptor".

lttng_enable_event(), lttng_enable_event_with_filter(), and lttng_enable_event_with_exclusions() expect such a structure to create or enable a recording event rule.

Most properties are members of the structure itself, but the following ones have their own dedicated accessors:

Linux user space probe location (when the lttng_event::type member is LTTNG_EVENT_USERSPACE_PROBE)

• lttng_event_get_userspace_probe_location()
• lttng_event_set_userspace_probe_location()

Event name exclusion patterns

lttng_event_get_exclusion_name()

Event payload and context filter expression

lttng_event_get_filter_expression()

Create an empty recording event rule descriptor with lttng_event_create().

A valid lttng_event structure satisfies the following constraints:

• If the lttng_event::type member is LTTNG_EVENT_PROBE or LTTNG_EVENT_FUNCTION, then the lttng_event_attr_u::probe member of lttng_event::attr is valid according to the documentation of lttng_event_probe_attr.
• If the lttng_event::type member is LTTNG_EVENT_USERSPACE_PROBE, then the recording event rule descriptor has a Linux user space probe location (you called lttng_event_set_userspace_probe_location() on it to set it).

Destroy a recording event rule descriptor with lttng_event_destroy().

Field Documentation

attr

union lttng_event_attr_u lttng_event::attr

Recording event rule context

Linux kprobe/kretprobe recording event rule configuration.

Only valid when the lttng_event::type member is LTTNG_EVENT_PROBE or LTTNG_EVENT_FUNCTION.

Instrumentation point descriptor context

Not applicable.

enabled

int32_t lttng_event::enabled

Recording event rule context

1 if this recording event rule is enabled, or 0 otherwise.

This is a read-only member.

See also

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

lttng_disable_event_ext() – Disables a recording event rule.

Instrumentation point descriptor context

Not applicable.

exclusion

unsigned char lttng_event::exclusion

Recording event rule context

1 if the recording event rule described by this has event name exclusion patterns (part of the event name condition), or 0 otherwise.

This is a read-only member: use the event_name_exclusion_count and event_name_exclusions parameters of lttng_enable_event_with_exclusions() when you create a recording event rule to set event name exclusion patterns.

If this member is 1, then get the actual event name exclusion patterns with lttng_event_get_exclusion_name_count() and lttng_event_get_exclusion_name().

Instrumentation point descriptor context

Not applicable.

filter

unsigned char lttng_event::filter

Recording event rule context

1 if the recording event rule described by this has an event payload and context filter expression, or 0 otherwise.

This is a read-only member: use the filter_expr parameter of lttng_enable_event_with_filter() or lttng_enable_event_with_exclusions() when you create a recording event rule to set an event payload and context filter expression.

If this member is 1, then get the actual filter expression string with lttng_event_get_filter_expression().

Instrumentation point descriptor context

Not applicable.

flags

enum lttng_event_flag lttng_event::flags

Recording event rule context

Not applicable.

Instrumentation point descriptor context

Instrumentation point flags (bitwise OR).

loglevel

int lttng_event::loglevel

Recording event rule context

Value of the instrumentation point log level condition.

This member must be one of the enumerators of lttng_loglevel, lttng_loglevel_jul, lttng_loglevel_log4j, lttng_loglevel_log4j2, or lttng_loglevel_python, depending on the tracing domain when you call lttng_enable_event(), lttng_enable_event_with_filter(), or lttng_enable_event_with_exclusions().

Instrumentation point descriptor context

For a user space tracepoint only: the static log level of the tracepoint, as set by LTTNG_UST_TRACEPOINT_LOGLEVEL() (see lttng-ust(3)).

loglevel_type

enum lttng_loglevel_type lttng_event::loglevel_type

Recording event rule context

Operand of the instrumentation point log level condition.

Instrumentation point descriptor context

Not applicable.

name

char lttng_event::name[LTTNG_SYMBOL_NAME_LEN]

Recording event rule context

Event name pattern condition.

If empty, lttng_enable_event(), lttng_enable_event_with_filter(), and lttng_enable_event_with_exclusions() use * (match events with any name).

If the lttng_event::type member is LTTNG_EVENT_PROBE, LTTNG_EVENT_FUNCTION, or LTTNG_EVENT_USERSPACE_PROBE, then this member is actually the name of the created Linux kprobe/kretprobe/user space probe instrumentation point (future event name).

Instrumentation point descriptor context

Name of the LTTng tracepoint, Linux system call, or Java/Python logger, depending on lttng_event::type.

pid

pid_t lttng_event::pid

Recording event rule context

Not applicable.

Instrumentation point descriptor context

ID of the process which offers the instrumentation point described by this structure.

type

enum lttng_event_type lttng_event::type

Recording event rule context

Instrumentation point type condition.

Instrumentation point descriptor context

Instrumentation point type.