LTTng user space tracepoint event rule API

Collaboration diagram for LTTng user space tracepoint event rule API:

Functions
enum lttng_event_rule_status	lttng_event_rule_user_tracepoint_add_name_pattern_exclusion (struct lttng_event_rule *rule, const char *exclusion_pattern)
	Adds the event name exclusion pattern exclusion_pattern to the LTTng user space tracepoint event rule rule.
struct lttng_event_rule *	lttng_event_rule_user_tracepoint_create (void)
	Creates a default LTTng user space tracepoint event rule.
enum lttng_event_rule_status	lttng_event_rule_user_tracepoint_get_filter (const struct lttng_event_rule *rule, const char **filter_expr)
	Sets *filter_expr to the event payload and context filter expression of the LTTng user space tracepoint event rule rule.
enum lttng_event_rule_status	lttng_event_rule_user_tracepoint_get_log_level_rule (const struct lttng_event_rule *event_rule, const struct lttng_log_level_rule **log_level_rule)
	Sets *log_level_rule to the instrumentation point log level rule of the LTTng user space tracepoint event rule event_rule.
enum lttng_event_rule_status	lttng_event_rule_user_tracepoint_get_name_pattern (const struct lttng_event_rule *rule, const char **pattern)
	Sets *pattern to the event name pattern of the LTTng user space tracepoint event rule rule.
enum lttng_event_rule_status	lttng_event_rule_user_tracepoint_get_name_pattern_exclusion_at_index (const struct lttng_event_rule *rule, unsigned int index, const char **exclusion_pattern)
	Sets *exclusion_pattern to the event name exclusion pattern of the LTTng user space tracepoint event rule rule at the index index.
enum lttng_event_rule_status	lttng_event_rule_user_tracepoint_get_name_pattern_exclusion_count (const struct lttng_event_rule *rule, unsigned int *count)
	Sets *count to the number of event name exclusion patterns of the LTTng user space tracepoint event rule rule.
enum lttng_event_rule_status	lttng_event_rule_user_tracepoint_set_filter (struct lttng_event_rule *rule, const char *filter_expr)
	Sets the event payload and context filter of the LTTng user space tracepoint event rule rule to filter_expr.
enum lttng_event_rule_status	lttng_event_rule_user_tracepoint_set_log_level_rule (struct lttng_event_rule *event_rule, const struct lttng_log_level_rule *log_level_rule)
	Sets the instrumentation point log level rule of the LTTng user space tracepoint event rule event_rule to log_level_rule.
enum lttng_event_rule_status	lttng_event_rule_user_tracepoint_set_name_pattern (struct lttng_event_rule *rule, const char *pattern)
	Sets the event name pattern of the LTTng user space tracepoint event rule rule to pattern.

Detailed Description

An LTTng user space tracepoint event rule is an event rule with the LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT type.

An LTTng user space tracepoint is a statically defined point in the source code of a C/C++ application/library with LTTng user space tracer macros.

Create an LTTng user space tracepoint event rule with lttng_event_rule_user_tracepoint_create().

The specific event rule conditions accessors of an LTTng user space tracepoint event rule are:

Condition	Setter	Getter
Event name	lttng_event_rule_user_tracepoint_set_name_pattern() and lttng_event_rule_user_tracepoint_add_name_pattern_exclusion()	lttng_event_rule_user_tracepoint_get_name_pattern() and lttng_event_rule_user_tracepoint_get_name_pattern_exclusion_at_index()
Instrumentation point log level	lttng_event_rule_user_tracepoint_set_log_level_rule()	lttng_event_rule_user_tracepoint_get_log_level_rule()
Event payload and context filter	lttng_event_rule_user_tracepoint_set_filter()	lttng_event_rule_user_tracepoint_get_filter()

Function Documentation

lttng_event_rule_user_tracepoint_add_name_pattern_exclusion()

enum lttng_event_rule_status lttng_event_rule_user_tracepoint_add_name_pattern_exclusion ( struct lttng_event_rule *  rule, const char *  exclusion_pattern  )

extern

Adds the event name exclusion pattern exclusion_pattern to the LTTng user space tracepoint event rule rule.

See the event name condition.

Parameters

[in]	rule	LTTng user space tracepoint event rule to which to add the event name exclusion pattern exclusion_pattern.
[in]	exclusion_pattern	Event name exclusion pattern to add to rule (copied).

Return values

LTTNG_EVENT_RULE_STATUS_OK	Success.
LTTNG_EVENT_RULE_STATUS_INVALID	Unsatisfied precondition.

Precondition

• rule is not NULL.
• rule has the type LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT.
• exclusion_pattern is not NULL.

See also

lttng_event_rule_user_tracepoint_set_name_pattern() – Set the event name pattern of an LTTng user space tracepoint event rule.

lttng_event_rule_user_tracepoint_get_name_pattern_exclusion_at_index() – Get an event name exclusion pattern of an LTTng user space tracepoint event rule by index.

lttng_event_rule_user_tracepoint_create()

struct lttng_event_rule * lttng_event_rule_user_tracepoint_create ( void  )

extern

Creates a default LTTng user space tracepoint event rule.

On success, the returned event rule has the following initial conditions:

Condition	Value	Setter(s)
Instrumentation point type	LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT	Not applicable
Event name	Any name	lttng_event_rule_user_tracepoint_set_name_pattern() lttng_event_rule_user_tracepoint_add_name_pattern_exclusion()
Instrumentation point log level	Any log level	lttng_event_rule_user_tracepoint_set_log_level_rule()
Event payload and context filter	No filter	lttng_event_rule_user_tracepoint_set_filter()

Returns

LTTng user space tracepoint event rule on success, or NULL on error.

Destroy the returned event rule with lttng_event_rule_destroy().

lttng_event_rule_user_tracepoint_get_filter()

enum lttng_event_rule_status lttng_event_rule_user_tracepoint_get_filter ( const struct lttng_event_rule *  rule, const char **  filter_expr  )

extern

Sets *filter_expr to the event payload and context filter expression of the LTTng user space tracepoint event rule rule.

See the event payload and context filter condition.

Parameters

[in]	rule	LTTng user space tracepoint event rule of which to get the event payload and context filter.
[out]	filter_expr	On success, this function sets *filter_expr to the event payload and context filter expression of rule. rule owns *filter_expr. *filter_expr remains valid until the next function call with rule.

Return values

LTTNG_EVENT_RULE_STATUS_OK	Success.
LTTNG_EVENT_RULE_STATUS_UNSET	rule has no event payload and context filter, which corresponds to the filter expression 1.
LTTNG_EVENT_RULE_STATUS_INVALID	Unsatisfied precondition.

Precondition

• rule is not NULL.
• rule has the type LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT.
• filter_expr is not NULL.

See also

lttng_event_rule_user_tracepoint_set_filter() – Set the event payload and context filter of an LTTng user space tracepoint event rule.

lttng_event_rule_user_tracepoint_get_log_level_rule()

enum lttng_event_rule_status lttng_event_rule_user_tracepoint_get_log_level_rule ( const struct lttng_event_rule *  event_rule, const struct lttng_log_level_rule **  log_level_rule  )

extern

Sets *log_level_rule to the instrumentation point log level rule of the LTTng user space tracepoint event rule event_rule.

See the instrumentation point log level condition.

Parameters

[in]	event_rule	LTTng user space tracepoint event rule of which to get the instrumentation point log level rule.
[out]	log_level_rule	On success, this function sets *log_level_rule to the instrumentation point log level rule of event_rule. event_rule owns *log_level_rule. *log_level_rule remains valid until the next function call with event_rule.

Return values

LTTNG_EVENT_RULE_STATUS_OK	Success.
LTTNG_EVENT_RULE_STATUS_UNSET	event_rule has no instrumentation point log level rule.
LTTNG_EVENT_RULE_STATUS_INVALID	Unsatisfied precondition.

Precondition

• rule is not NULL.
• rule has the type LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT.
• log_level_rule is not NULL.

See also

lttng_event_rule_user_tracepoint_set_log_level_rule() – Set the instrumentation point log level rule of an LTTng user space tracepoint event rule.

lttng_event_rule_user_tracepoint_get_name_pattern()

enum lttng_event_rule_status lttng_event_rule_user_tracepoint_get_name_pattern ( const struct lttng_event_rule *  rule, const char **  pattern  )

extern

Sets *pattern to the event name pattern of the LTTng user space tracepoint event rule rule.

See the event name condition.

Parameters

[in]	rule	LTTng user space tracepoint event rule of which to get the event name pattern.
[out]	pattern	On success, this function sets *pattern to the event name pattern of rule. rule owns *pattern. *pattern remains valid until the next function call with rule.

Return values

LTTNG_EVENT_RULE_STATUS_OK	Success.
LTTNG_EVENT_RULE_STATUS_UNSET	rule has no event name pattern, which corresponds to the pattern * (any event name).
LTTNG_EVENT_RULE_STATUS_INVALID	Unsatisfied precondition.

Precondition

• rule is not NULL.
• rule has the type LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT.
• pattern is not NULL.

See also

lttng_event_rule_user_tracepoint_set_name_pattern() – Set the event name pattern of an LTTng user space tracepoint event rule.

lttng_event_rule_user_tracepoint_get_name_pattern_exclusion_at_index()

enum lttng_event_rule_status lttng_event_rule_user_tracepoint_get_name_pattern_exclusion_at_index ( const struct lttng_event_rule *  rule, unsigned int  index, const char **  exclusion_pattern  )

extern

Sets *exclusion_pattern to the event name exclusion pattern of the LTTng user space tracepoint event rule rule at the index index.

See the event name condition.

Parameters

[in]	rule	LTTng user space tracepoint event rule of which to get the event name exclusion pattern at the index index.
[in]	index	Index of the event name exclusion pattern to get from rule.
[in]	exclusion_pattern	On success, this function sets *exclusion_pattern to the event name exclusion pattern of rule at the index index. event_rule owns *exclusion_pattern. *exclusion_pattern remains valid until the next function call with event_rule.

Return values

LTTNG_EVENT_RULE_STATUS_OK	Success.
LTTNG_EVENT_RULE_STATUS_INVALID	Unsatisfied precondition.

Precondition

• rule is not NULL.
• rule has the type LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT.
• index is less than the number of event name exclusion patterns of rule (as given by lttng_event_rule_user_tracepoint_get_name_pattern_exclusion_count()).
• exclusion_pattern is not NULL.

See also

lttng_event_rule_user_tracepoint_get_name_pattern_exclusion_count() – Get the number of event name exclusion patterns of an LTTng user space tracepoint event rule.

lttng_event_rule_user_tracepoint_add_name_pattern_exclusion() – Adds an event name exclusion pattern to an LTTng user space tracepoint event rule.

lttng_event_rule_user_tracepoint_get_name_pattern_exclusion_count()

enum lttng_event_rule_status lttng_event_rule_user_tracepoint_get_name_pattern_exclusion_count ( const struct lttng_event_rule *  rule, unsigned int *  count  )

extern

Sets *count to the number of event name exclusion patterns of the LTTng user space tracepoint event rule rule.

See the event name condition.

Parameters

[in]	rule	LTTng user space tracepoint event rule of which to get the number of event name exclusion patterns.
[out]	count	On success, this function sets *count to the number of event name exclusion patterns of rule.

Return values

LTTNG_EVENT_RULE_STATUS_OK	Success.
LTTNG_EVENT_RULE_STATUS_INVALID	Unsatisfied precondition.

Precondition

• rule is not NULL.
• rule has the type LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT.
• count is not NULL.

See also

lttng_event_rule_user_tracepoint_get_name_pattern_exclusion_at_index() – Get an event name exclusion pattern of an LTTng user space tracepoint event rule by index.

lttng_event_rule_user_tracepoint_set_filter()

enum lttng_event_rule_status lttng_event_rule_user_tracepoint_set_filter ( struct lttng_event_rule *  rule, const char *  filter_expr  )

extern

Sets the event payload and context filter of the LTTng user space tracepoint event rule rule to filter_expr.

See the event payload and context filter condition.

Parameters

[in]	rule	LTTng user space tracepoint event rule of which to set the event payload and context filter.
[in]	filter_expr	Event payload and context filter expression of rule (copied).

Return values

LTTNG_EVENT_RULE_STATUS_OK	Success.
LTTNG_EVENT_RULE_STATUS_INVALID	Unsatisfied precondition.

Precondition

• rule is not NULL.
• rule has the type LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT.
• filter_expr is not NULL.
• filter_expr is a valid filter expression (see the event payload and context filter condition).

See also

lttng_event_rule_user_tracepoint_get_filter() – Get the event payload and context filter of an LTTng user space tracepoint event rule.

lttng_event_rule_user_tracepoint_set_log_level_rule()

enum lttng_event_rule_status lttng_event_rule_user_tracepoint_set_log_level_rule ( struct lttng_event_rule *  event_rule, const struct lttng_log_level_rule *  log_level_rule  )

extern

Sets the instrumentation point log level rule of the LTTng user space tracepoint event rule event_rule to log_level_rule.

See the instrumentation point log level condition.

Parameters

[in]	event_rule	LTTng user space tracepoint event rule of which to set the instrumentation point log level rule.
[in]	log_level_rule	Instrumentation point log level rule of event_rule (copied).

Return values

LTTNG_EVENT_RULE_STATUS_OK	Success.
LTTNG_EVENT_RULE_STATUS_INVALID	Unsatisfied precondition.

Precondition

• event_rule is not NULL.
• event_rule has the type LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT.
• log_level_rule is not NULL.

See also

lttng_event_rule_user_tracepoint_get_log_level_rule() – Get the instrumentation point log level rule of an LTTng user space tracepoint event rule.

lttng_event_rule_user_tracepoint_set_name_pattern()

enum lttng_event_rule_status lttng_event_rule_user_tracepoint_set_name_pattern ( struct lttng_event_rule *  rule, const char *  pattern  )

extern

Sets the event name pattern of the LTTng user space tracepoint event rule rule to pattern.

See the event name condition.

Parameters

[in]	rule	LTTng user space tracepoint event rule of which to set the event name pattern.
[in]	pattern	New event name pattern of rule (copied).

Return values

LTTNG_EVENT_RULE_STATUS_OK	Success.
LTTNG_EVENT_RULE_STATUS_INVALID	Unsatisfied precondition.

Precondition

• rule is not NULL.
• rule has the type LTTNG_EVENT_RULE_TYPE_USER_TRACEPOINT.
• pattern is not NULL.
• pattern is not empty.

See also

lttng_event_rule_user_tracepoint_get_name_pattern() – Get the event name pattern of an LTTng user space tracepoint event rule.

lttng_event_rule_user_tracepoint_add_name_pattern_exclusion() – Add an event name exclusion pattern to an LTTng user space tracepoint event rule.