“Event rule matches” trigger condition API

Collaboration diagram for “Event rule matches” trigger condition API:

Modules
	Event rule API
	Event expression API
	Event field value API

Enumerations
enum	lttng_evaluation_event_rule_matches_status { LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_OK , LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_NONE , LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_INVALID }
	Return type of lttng_evaluation_event_rule_matches_get_captured_values(). More...

Functions
enum lttng_condition_status	lttng_condition_event_rule_matches_append_capture_descriptor (struct lttng_condition *condition, struct lttng_event_expr *expr)
	Appends a capture descriptor with the event expression expr to the “event rule matches” trigger condition condition.
struct lttng_condition *	lttng_condition_event_rule_matches_create (struct lttng_event_rule *rule)
	Creates an “event rule matches” trigger condition to execute an action when the event rule rule matches an LTTng event.
const struct lttng_event_expr *	lttng_condition_event_rule_matches_get_capture_descriptor_at_index (const struct lttng_condition *condition, unsigned int index)
	Returns the capture descriptor of the “event rule matches” trigger condition condition at the index index.
enum lttng_condition_status	lttng_condition_event_rule_matches_get_capture_descriptor_count (const struct lttng_condition *condition, unsigned int *count)
	Sets *count to the number of capture descriptors of the “event rule matches” trigger condition condition.
enum lttng_condition_status	lttng_condition_event_rule_matches_get_rule (const struct lttng_condition *condition, const struct lttng_event_rule **rule)
	Sets *rule to the event rule of the “event rule matches” trigger condition condition.
enum lttng_evaluation_event_rule_matches_status	lttng_evaluation_event_rule_matches_get_captured_values (const struct lttng_evaluation *evaluation, const struct lttng_event_field_value **field_val)
	Sets *field_val to the array event field value of the “event rule matches” trigger condition evaluation evaluation containing its captured field values.

Detailed Description

An “event rule matches” trigger condition is considered satisfied when its event rule matches an LTTng event.

An “event rule matches” trigger condition has the type LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES.

Create an “event rule matches” trigger condition with lttng_condition_event_rule_matches_create().

Get the event rule of an “event rule matches” trigger condition with lttng_condition_event_rule_matches_get_rule().

Evaluation

When a trigger with an “event rule matches” condition fires, LTTng can evaluate one or more event expressions and then capture theirs results. As of LTTng-tools 16.2, the only available event expressions are event payload and context field references. With the “notify” action, a user may then read the captured values from the condition evaluation with lttng_evaluation_event_rule_matches_get_captured_values().

To make LTTng capture event payload and context fields when an “event rule matches” trigger condition is satisfied, append capture descriptors to the condition object with lttng_condition_event_rule_matches_append_capture_descriptor() before you create the trigger with lttng_trigger_create().

Get the capture descriptors of an “event rule matches” trigger condition with lttng_condition_event_rule_matches_get_capture_descriptor_count() and lttng_condition_event_rule_matches_get_capture_descriptor_at_index().

Note

As of LTTng 16.2, the total serialized size of all the captured values of a single evaluation is limited (512 bytes for the Linux kernel tracing domain; a little less than one memory page for the user space one).

When this limit is reached, the values which don't fit are missing from the evaluation: reading them with lttng_event_field_value_array_get_element_at_index() makes that function return LTTNG_EVENT_FIELD_VALUE_STATUS_UNAVAILABLE (see lttng_condition_event_rule_matches_append_capture_descriptor()).

Enumeration Type Documentation

lttng_evaluation_event_rule_matches_status

enum lttng_evaluation_event_rule_matches_status

Return type of lttng_evaluation_event_rule_matches_get_captured_values().

Enumerator
LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_OK	Success.
LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_NONE	The condition of the evaluation has no capture descriptors.
LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_INVALID	Unsatisfied precondition.

Function Documentation

lttng_condition_event_rule_matches_append_capture_descriptor()

enum lttng_condition_status lttng_condition_event_rule_matches_append_capture_descriptor ( struct lttng_condition *  condition, struct lttng_event_expr *  expr  )

extern

Appends a capture descriptor with the event expression expr to the “event rule matches” trigger condition condition.

When a trigger with condition fires, LTTng evaluates expr and captures the result. With the “notify” action, a user may read the captured values from the condition evaluation with lttng_evaluation_event_rule_matches_get_captured_values().

Note

As of LTTng 16.2, the total serialized size of all the captured values of a single evaluation of condition is limited (512 bytes for the Linux kernel tracing domain; a little less than one memory page for the user space one).

There's therefore no fixed maximum number of capture descriptors, but the more you append, and the larger the captured fields, the more likely it is to reach this limit.

LTTng captures values in the order of their capture descriptors: when a value doesn't fit, it's missing from the evaluation (reading it with lttng_event_field_value_array_get_element_at_index() returns LTTNG_EVENT_FIELD_VALUE_STATUS_UNAVAILABLE) and LTTng proceeds with the next descriptor.

Parameters

[in]	condition	“Event rule matches” trigger condition to which to append a capture descriptor.
[in]	expr	Event expression of the capture descriptor to append to condition. On success, the ownership of this expression is moved to condition.

Return values

LTTNG_CONDITION_STATUS_OK	Success.
LTTNG_CONDITION_STATUS_INVALID	Unsatisfied precondition.
LTTNG_CONDITION_STATUS_UNSUPPORTED	condition doesn't support event field value capturing considering its event rule.
LTTNG_CONDITION_STATUS_ERROR	Memory error.

Precondition

• condition is not NULL.
• condition has the type LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES.
• expr is not NULL.

lttng_condition_event_rule_matches_create()

struct lttng_condition * lttng_condition_event_rule_matches_create ( struct lttng_event_rule *  rule )

extern

Creates an “event rule matches” trigger condition to execute an action when the event rule rule matches an LTTng event.

On success, the returned trigger condition has no capture descriptors: append capture descriptors with lttng_condition_event_rule_matches_append_capture_descriptor().

Parameters

[in]

rule

Event rule of the “event rule matches” trigger condition to create (not moved).

Returns

Trigger condition with the type LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES on success, or NULL on error.

Destroy the returned trigger condition with lttng_condition_destroy().

Precondition

• rule is not NULL.

lttng_condition_event_rule_matches_get_capture_descriptor_at_index()

const struct lttng_event_expr * lttng_condition_event_rule_matches_get_capture_descriptor_at_index ( const struct lttng_condition *  condition, unsigned int  index  )

extern

Returns the capture descriptor of the “event rule matches” trigger condition condition at the index index.

Parameters

[in]	condition	“Event rule matches” trigger condition of which to get the capture descriptor at the index index.
[in]	index	Index of the capture descriptor to get from condition.

Returns

Capture descriptor of the “event rule matches” trigger condition condition at the index index, or NULL on error.

condition owns the returned capture descriptor.

The returned capture descriptor remains valid as long as condition exists.

Precondition

• condition is not NULL.
• condition has the type LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES.
• index is less than the number of capture descriptors (as returned by lttng_condition_event_rule_matches_get_capture_descriptor_count()) of condition.

See also

lttng_condition_event_rule_matches_get_capture_descriptor_count() – Get the number of capture descriptors of an “event rule matches” trigger condition.

lttng_condition_event_rule_matches_get_capture_descriptor_count()

enum lttng_condition_status lttng_condition_event_rule_matches_get_capture_descriptor_count ( const struct lttng_condition *  condition, unsigned int *  count  )

extern

Sets *count to the number of capture descriptors of the “event rule matches” trigger condition condition.

Parameters

[in]	condition	“Event rule matches” trigger condition of which to get the number of capture descriptors.
[out]	count	On success, this function sets *count to the number of capture descriptors of condition.

Return values

LTTNG_CONDITION_STATUS_OK	Success.
LTTNG_CONDITION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• condition is not NULL.
• condition has the type LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES.
• count is not NULL.

See also

lttng_condition_event_rule_matches_get_capture_descriptor_at_index() – Get the capture descriptor of an “event rule matches” trigger condition by index.

lttng_condition_event_rule_matches_get_rule()

enum lttng_condition_status lttng_condition_event_rule_matches_get_rule ( const struct lttng_condition *  condition, const struct lttng_event_rule **  rule  )

extern

Sets *rule to the event rule of the “event rule matches” trigger condition condition.

Parameters

[in]	condition	“Event rule matches” trigger condition of which to get the event rule.
[out]	rule	On success, this function sets *rule to the event rule of condition. condition owns *rule. *rule remains valid until the next function call with condition.

Return values

LTTNG_CONDITION_STATUS_OK	Success.
LTTNG_CONDITION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• condition is not NULL.
• condition has the type LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES.
• rule is not NULL.

lttng_evaluation_event_rule_matches_get_captured_values()

enum lttng_evaluation_event_rule_matches_status lttng_evaluation_event_rule_matches_get_captured_values ( const struct lttng_evaluation *  evaluation, const struct lttng_event_field_value **  field_val  )

extern

Sets *field_val to the array event field value of the “event rule matches” trigger condition evaluation evaluation containing its captured field values.

Each element of the returned array event field value is described by the capture descriptor at the same index in the condition of evaluation (see lttng_condition_event_rule_matches_get_capture_descriptor_count() and lttng_condition_event_rule_matches_get_capture_descriptor_at_index()).

Note

Because the total serialized size of the captured values of a single evaluation is limited (see lttng_condition_event_rule_matches_append_capture_descriptor()), some elements of the returned array may be unavailable: reading them with lttng_event_field_value_array_get_element_at_index() makes that function return LTTNG_EVENT_FIELD_VALUE_STATUS_UNAVAILABLE.

Parameters

[in]	evaluation	“Event rule matches” trigger condition evaluation of which to get the captured event field values.
[out]	field_val	On success, this function sets *field_val to the captured event field values of evaluation. *field_val has the type LTTNG_EVENT_FIELD_VALUE_TYPE_ARRAY. evaluation owns *field_val. *field_val remains valid until the next function call with evaluation.

Return values

LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_OK	Success.
LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_NONE	The condition of evaluation has no capture descriptors.
LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_INVALID	Unsatisfied precondition.

Precondition

• evaluation is not NULL.
• evaluation has the type LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES.
• field_val is not NULL.