Trigger condition API

Collaboration diagram for Trigger condition API:

Modules
	“Recording session consumed data size becomes greater than” trigger condition API
	“Channel buffer usage becomes greater/less than” trigger condition API
	“Recording session rotation starts/finishes” trigger condition API
	“Event rule matches” trigger condition API

Data Structures
struct	lttng_condition
	Trigger condition (opaque type). More...
struct	lttng_evaluation
	Trigger condition evaluation (opaque type). More...

Enumerations
enum	lttng_condition_status {   LTTNG_CONDITION_STATUS_OK , LTTNG_CONDITION_STATUS_ERROR , LTTNG_CONDITION_STATUS_UNKNOWN , LTTNG_CONDITION_STATUS_INVALID ,   LTTNG_CONDITION_STATUS_UNSET , LTTNG_CONDITION_STATUS_UNSUPPORTED }
	Return type of trigger condition API functions. More...
enum	lttng_condition_type {   LTTNG_CONDITION_TYPE_SESSION_CONSUMED_SIZE , LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH , LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW , LTTNG_CONDITION_TYPE_SESSION_ROTATION_ONGOING ,   LTTNG_CONDITION_TYPE_SESSION_ROTATION_COMPLETED , LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES , LTTNG_CONDITION_TYPE_UNKNOWN }
	Trigger condition type. More...
enum	lttng_evaluation_status { LTTNG_EVALUATION_STATUS_OK , LTTNG_EVALUATION_STATUS_ERROR , LTTNG_EVALUATION_STATUS_INVALID , LTTNG_EVALUATION_STATUS_UNKNOWN , LTTNG_EVALUATION_STATUS_UNSET }
	Return type of trigger condition evaluation API functions. More...

Functions
void	lttng_condition_destroy (struct lttng_condition *condition)
	Destroys the trigger condition condition.
enum lttng_condition_type	lttng_condition_get_type (const struct lttng_condition *condition)
	Returns the type of the trigger condition condition.
void	lttng_evaluation_destroy (struct lttng_evaluation *evaluation)
	Destroys the trigger condition evaluation evaluation.
enum lttng_condition_type	lttng_evaluation_get_type (const struct lttng_evaluation *evaluation)
	Returns the condition type of the trigger condition evaluation evaluation.

Detailed Description

A trigger condition is the part of a trigger which must be satisfied for LTTng to execute its action.

As of LTTng-tools 15.2, the following trigger conditions are available:

Condition type	Type enumerator	Creation function
Recording session consumed data size becomes greater than	LTTNG_CONDITION_TYPE_SESSION_CONSUMED_SIZE	lttng_condition_session_consumed_size_create()
Channel buffer usage becomes greater than	LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH	lttng_condition_buffer_usage_high_create()
Channel buffer usage becomes less than	LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW	lttng_condition_buffer_usage_low_create()
Recording session rotation starts	LTTNG_CONDITION_TYPE_SESSION_ROTATION_ONGOING	lttng_condition_session_rotation_ongoing_create()
Recording session rotation finishes	LTTNG_CONDITION_TYPE_SESSION_ROTATION_COMPLETED	lttng_condition_session_rotation_completed_create()
Event rule matches	LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES	lttng_condition_event_rule_matches_create()

Get the type of a trigger condition with lttng_condition_get_type().

Destroy a trigger condition with lttng_condition_destroy().

Evaluation

When a trigger with a some condition C fires, LTTng can capture some data. With the “notify” action, a user may then read the captured value(s) from the evaluation of C (through lttng_notification_get_evaluation()).

The opaque type of a trigger condition evaluation is lttng_evaluation.

Trigger condition and condition evaluation objects share the same type enumeration: get the condition type of an evaluation with lttng_evaluation_get_type().

The available captured values are, depending on the trigger condition type:

Condition type(s)	Captured value(s)	Access
LTTNG_CONDITION_TYPE_SESSION_CONSUMED_SIZE	Total recording session consumed size.	lttng_evaluation_session_consumed_size_get_consumed_size()
LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH and LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW	Channel buffer usage ratio and size.	lttng_evaluation_buffer_usage_get_usage_ratio() and lttng_evaluation_buffer_usage_get_usage()
LTTNG_CONDITION_TYPE_SESSION_ROTATION_ONGOING	Recording session rotation ID.	lttng_evaluation_session_rotation_get_id()
LTTNG_CONDITION_TYPE_SESSION_ROTATION_COMPLETED	Recording session rotation ID and resulting trace archive location.	lttng_evaluation_session_rotation_get_id() and lttng_evaluation_session_rotation_completed_get_location()
LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES	Captured event payload and context fields.	lttng_evaluation_event_rule_matches_get_captured_values()

Destroy a trigger condition evaluation with lttng_evaluation_destroy().

Enumeration Type Documentation

lttng_condition_status

enum lttng_condition_status

Return type of trigger condition API functions.

Enumerator
LTTNG_CONDITION_STATUS_OK	Success.
LTTNG_CONDITION_STATUS_ERROR	Error.
LTTNG_CONDITION_STATUS_INVALID	Unsatisfied precondition.
LTTNG_CONDITION_STATUS_UNSET	Not set.
LTTNG_CONDITION_STATUS_UNSUPPORTED	Unsupported feature.

lttng_condition_type

enum lttng_condition_type

Trigger condition type.

Get the type of a trigger condition with lttng_condition_get_type().

Enumerator
LTTNG_CONDITION_TYPE_SESSION_CONSUMED_SIZE	Recording session consumed data size becomes greater than".
LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH	Channel buffer usage becomes greater than.
LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW	Channel buffer usage becomes less than.
LTTNG_CONDITION_TYPE_SESSION_ROTATION_ONGOING	Recording session rotation starts.
LTTNG_CONDITION_TYPE_SESSION_ROTATION_COMPLETED	Recording session rotation finishes.
LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES	Event rule matches.
LTTNG_CONDITION_TYPE_UNKNOWN	Unknown (error).

lttng_evaluation_status

enum lttng_evaluation_status

Return type of trigger condition evaluation API functions.

Enumerator
LTTNG_EVALUATION_STATUS_OK	Success.
LTTNG_EVALUATION_STATUS_INVALID	Unsatisfied precondition.

Function Documentation

lttng_condition_destroy()

void lttng_condition_destroy ( struct lttng_condition *  condition )

extern

Destroys the trigger condition condition.

Parameters

[in]

condition

Trigger condition to destroy. May be NULL.

lttng_condition_get_type()

enum lttng_condition_type lttng_condition_get_type ( const struct lttng_condition *  condition )

extern

Returns the type of the trigger condition condition.

Parameters

[in]

condition

Trigger condition of which to get the type.

Returns

Type of condition.

Precondition

• condition is not NULL.

lttng_evaluation_destroy()

void lttng_evaluation_destroy ( struct lttng_evaluation *  evaluation )

extern

Destroys the trigger condition evaluation evaluation.

Parameters

[in]

evaluation

Trigger condition evaluation to destroy. May be NULL.

lttng_evaluation_get_type()

enum lttng_condition_type lttng_evaluation_get_type ( const struct lttng_evaluation *  evaluation )

extern

Returns the condition type of the trigger condition evaluation evaluation.

Parameters

[in]

evaluation

Trigger condition evaluation of which to get the condition type.

Returns

Type of evaluation.

Precondition

• evaluation is not NULL.