“Event record channel buffer usage becomes greater/less than” trigger condition API

Collaboration diagram for “Event record channel buffer usage becomes greater/less than” trigger condition API:

Functions
enum lttng_condition_status	lttng_condition_buffer_usage_get_channel_name (const struct lttng_condition *condition, const char **channel_name)
	Sets *channel_name to the target event record channel name of the “event record channel buffer usage becomes greater/less than” trigger condition condition.
enum lttng_condition_status	lttng_condition_buffer_usage_get_domain_type (const struct lttng_condition *condition, enum lttng_domain_type *domain)
	Sets *domain to the target tracing domain of the “event record channel buffer usage becomes greater/less than” trigger condition condition.
enum lttng_condition_status	lttng_condition_buffer_usage_get_session_name (const struct lttng_condition *condition, const char **session_name)
	Sets *session_name to the target recording session name of the “event record channel buffer usage becomes greater/less than” trigger condition condition.
enum lttng_condition_status	lttng_condition_buffer_usage_get_threshold (const struct lttng_condition *condition, uint64_t *threshold)
	Sets *threshold to the event record channel buffer usage size (bytes) threshold of the “event record channel buffer usage becomes greater/less than” trigger condition condition.
enum lttng_condition_status	lttng_condition_buffer_usage_get_threshold_ratio (const struct lttng_condition *condition, double *threshold)
	Sets *threshold to the \lt_obj_event record channel buffer usage ratio threshold of the “event record channel buffer usage becomes greater/less than” trigger condition condition.
struct lttng_condition *	lttng_condition_buffer_usage_high_create (void)
	Creates an initial “event record channel buffer usage becomes greater than” trigger condition to execute an action when the ring buffer usage of a given event record channel becomes greater than some configured threshold.
struct lttng_condition *	lttng_condition_buffer_usage_low_create (void)
	Creates an initial “event record channel buffer usage becomes less than” trigger condition to execute an action when the ring buffer usage of a given event record channel becomes less than some configured threshold.
enum lttng_condition_status	lttng_condition_buffer_usage_set_channel_name (struct lttng_condition *condition, const char *channel_name)
	Sets the target event record channel name of the “event record channel buffer usage becomes greater/less than” trigger condition condition to channel_name.
enum lttng_condition_status	lttng_condition_buffer_usage_set_domain_type (struct lttng_condition *condition, enum lttng_domain_type domain)
	Sets the target tracing domain of the “event record channel buffer usage becomes greater/less than” trigger condition condition to domain.
enum lttng_condition_status	lttng_condition_buffer_usage_set_session_name (struct lttng_condition *condition, const char *session_name)
	Sets the target recording session name of the “event record channel buffer usage becomes greater/less than” trigger condition condition to session_name.
enum lttng_condition_status	lttng_condition_buffer_usage_set_threshold (struct lttng_condition *condition, uint64_t threshold)
	Sets the \lt_obj_event record channel buffer usage size threshold of the “event record channel buffer usage becomes greater/less than” trigger condition condition to threshold.
enum lttng_condition_status	lttng_condition_buffer_usage_set_threshold_ratio (struct lttng_condition *condition, double threshold)
	Sets the \lt_obj_event record channel buffer usage ratio threshold of the “event record channel buffer usage becomes greater/less than” trigger condition condition to threshold.
enum lttng_evaluation_status	lttng_evaluation_buffer_usage_get_usage (const struct lttng_evaluation *evaluation, uint64_t *usage)
	Sets *usage to the captured event record channel buffer usage size of the “event record channel buffer usage becomes greater/less than” trigger condition evaluation evaluation.
enum lttng_evaluation_status	lttng_evaluation_buffer_usage_get_usage_ratio (const struct lttng_evaluation *evaluation, double *usage)
	Sets *usage to the captured event record channel buffer usage ratio of the “event record channel buffer usage becomes greater/less than” trigger condition evaluation evaluation.

Detailed Description

A “event record channel buffer usage becomes greater/less than” trigger condition is considered satisfied when the ring buffer usage of a given event record channel becomes greater or less than some configured threshold.

An “event record channel buffer usage becomes greater than” trigger condition has the type LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH.

An “event record channel buffer usage becomes less than” trigger condition has the type LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW.

Every time the monitor timer of an event record channel expires, LTTng updates its statistics, including its buffer usage. This is when LTTng tries to evaluate “event record channel buffer usage becomes greater/less than” conditions.

To create a valid “event record channel buffer usage becomes greater/less than” trigger condition:

1. Create the initial trigger condition with one of:

   Event record channel buffer usage becomes greater than

   lttng_condition_buffer_usage_high_create()

   Event record channel buffer usage becomes less than

   lttng_condition_buffer_usage_low_create()

2. Set a buffer usage threshold with one of:

   By ratio (0 to 1)

   lttng_condition_buffer_usage_set_threshold_ratio()

   By size (bytes)

   lttng_condition_buffer_usage_set_threshold()

3. Set a target recording session name with lttng_condition_buffer_usage_set_session_name().
4. Set a target tracing domain with lttng_condition_buffer_usage_set_domain_type().
5. Set a target event record channel name with lttng_condition_buffer_usage_set_channel_name().

Get the buffer usage threshold of an “event record channel buffer usage becomes greater/less than” trigger condition with lttng_condition_buffer_usage_get_threshold_ratio() or lttng_condition_buffer_usage_get_threshold().

Get the target recording session name, tracing domain, and event record channel name of an “event record channel buffer usage becomes greater/less than” trigger condition with lttng_condition_buffer_usage_get_session_name(), lttng_condition_buffer_usage_get_domain_type(), and lttng_condition_buffer_usage_get_channel_name().

Evaluation

When a trigger with an “event record channel buffer usage becomes greater/less than” condition fires, LTTng captures the current ring buffer usage. With the “notify” action, a user may then read the captured value from the condition evaluation with lttng_evaluation_buffer_usage_get_usage_ratio() and lttng_evaluation_buffer_usage_get_usage().

Function Documentation

lttng_condition_buffer_usage_get_channel_name()

enum lttng_condition_status lttng_condition_buffer_usage_get_channel_name ( const struct lttng_condition *  condition, const char **  channel_name  )

extern

Sets *channel_name to the target event record channel name of the “event record channel buffer usage becomes greater/less than” trigger condition condition.

Parameters

[in]	condition	“Event record channel buffer usage becomes greater/less than” trigger condition of which to get the target event record channel name.
[out]	channel_name	On success, this function sets *channel_name to the target event record channel name of condition. condition owns *channel_name. *channel_name remains valid until the next function call with condition.

Return values

LTTNG_CONDITION_STATUS_OK	Success.
LTTNG_CONDITION_STATUS_UNSET	condition has no target event record channel name.
LTTNG_CONDITION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• condition is not NULL.
• condition has the type LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH or LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW.
• channel_name is not NULL.

See also

lttng_condition_buffer_usage_set_channel_name() – Set the target event record channel name of a “event record channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_get_domain_type()

enum lttng_condition_status lttng_condition_buffer_usage_get_domain_type ( const struct lttng_condition *  condition, enum lttng_domain_type *  domain  )

extern

Sets *domain to the target tracing domain of the “event record channel buffer usage becomes greater/less than” trigger condition condition.

Parameters

[in]	condition	“Event record channel buffer usage becomes greater/less than” trigger condition of which to get the target tracing domain.
[out]	domain	On success, this function sets *domain to the target tracing domain of condition. condition owns *domain. *domain remains valid until the next function call with condition.

Return values

LTTNG_CONDITION_STATUS_OK	Success.
LTTNG_CONDITION_STATUS_UNSET	condition has no target tracing domain.
LTTNG_CONDITION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• condition is not NULL.
• condition has the type LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH or LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW.

See also

lttng_condition_buffer_usage_set_domain_type() – Set the target tracing domain of a “event record channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_get_session_name()

enum lttng_condition_status lttng_condition_buffer_usage_get_session_name ( const struct lttng_condition *  condition, const char **  session_name  )

extern

Sets *session_name to the target recording session name of the “event record channel buffer usage becomes greater/less than” trigger condition condition.

Parameters

[in]	condition	“Event record channel buffer usage becomes greater/less than” trigger condition of which to get the target recording session name.
[out]	session_name	On success, this function sets *session_name to the target recording session name of condition. condition owns *session_name. *session_name remains valid until the next function call with condition.

Return values

LTTNG_CONDITION_STATUS_OK	Success.
LTTNG_CONDITION_STATUS_UNSET	condition has no target recording session name.
LTTNG_CONDITION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• condition is not NULL.
• condition has the type LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH or LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW.
• session_name is not NULL.

See also

lttng_condition_buffer_usage_set_session_name() – Set the target recording session name of a “event record channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_get_threshold()

enum lttng_condition_status lttng_condition_buffer_usage_get_threshold ( const struct lttng_condition *  condition, uint64_t *  threshold  )

extern

Sets *threshold to the event record channel buffer usage size (bytes) threshold of the “event record channel buffer usage becomes greater/less than” trigger condition condition.

Parameters

[in]	condition	“Event record channel buffer usage becomes greater/less than” trigger condition of which to get the event record channel buffer usage size threshold.
[out]	threshold	On success, this function sets *threshold to the buffer usage size (bytes) threshold of condition.

Return values

LTTNG_CONDITION_STATUS_OK	Success.
LTTNG_CONDITION_STATUS_UNSET	condition has no event record channel buffer usage size threshold, although it may have an event record channel buffer usage ratio threshold (see lttng_condition_buffer_usage_get_threshold_ratio()).
LTTNG_CONDITION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• condition is not NULL.
• condition has the type LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH or LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW.
• threshold is not NULL.

See also

lttng_condition_buffer_usage_set_threshold() – Set the event record channel buffer usage size threshold of a “event record channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_get_threshold_ratio() – Get the event record channel buffer usage ratio threshold of a “event record channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_get_threshold_ratio()

enum lttng_condition_status lttng_condition_buffer_usage_get_threshold_ratio ( const struct lttng_condition *  condition, double *  threshold  )

extern

Sets *threshold to the \lt_obj_event record channel buffer usage ratio threshold of the “event record channel buffer usage becomes greater/less than” trigger condition condition.

Parameters

[in]	condition	“Event record channel buffer usage becomes greater/less than” trigger condition of which to get the event record channel buffer usage ratio threshold.
[out]	threshold	On success, this function sets *threshold to the event record channel buffer usage ratio (between 0 and 1) threshold of condition.

Return values

LTTNG_CONDITION_STATUS_OK	Success.
LTTNG_CONDITION_STATUS_UNSET	condition has no event record channel buffer usage ratio threshold, although it may have an event record channel buffer usage size threshold (see lttng_condition_buffer_usage_get_threshold()).
LTTNG_CONDITION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• condition is not NULL.
• condition has the type LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH or LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW.
• threshold is not NULL.

See also

lttng_condition_buffer_usage_set_threshold_ratio() – Set the event record channel buffer usage ratio threshold of a “event record channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_get_threshold() – Get the event record channel buffer usage size threshold of a “event record channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_high_create()

struct lttng_condition * lttng_condition_buffer_usage_high_create ( void  )

extern

Creates an initial “event record channel buffer usage becomes greater than” trigger condition to execute an action when the ring buffer usage of a given event record channel becomes greater than some configured threshold.

On success, the returned trigger condition isn't valid yet; you must:

• Set a target recording session name with lttng_condition_buffer_usage_set_session_name().
• Set a target tracing domain with lttng_condition_buffer_usage_set_domain_type().
• Set a target event record channel name with lttng_condition_buffer_usage_set_channel_name().
• Set an event record channel buffer usage threshold with lttng_condition_buffer_usage_set_threshold_ratio() or lttng_condition_buffer_usage_set_threshold().

Returns

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

Destroy the returned trigger condition with lttng_condition_destroy().

lttng_condition_buffer_usage_low_create()

struct lttng_condition * lttng_condition_buffer_usage_low_create ( void  )

extern

Creates an initial “event record channel buffer usage becomes less than” trigger condition to execute an action when the ring buffer usage of a given event record channel becomes less than some configured threshold.

On success, the returned trigger condition isn't valid yet; you must:

• Set a target recording session name with lttng_condition_buffer_usage_set_session_name().
• Set a target tracing domain with lttng_condition_buffer_usage_set_domain_type().
• Set a target event record channel name with lttng_condition_buffer_usage_set_channel_name().
• Set an event record channel buffer usage threshold with lttng_condition_buffer_usage_set_threshold_ratio() or lttng_condition_buffer_usage_set_threshold().

Returns

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

Destroy the returned trigger condition with lttng_condition_destroy().

lttng_condition_buffer_usage_set_channel_name()

enum lttng_condition_status lttng_condition_buffer_usage_set_channel_name ( struct lttng_condition *  condition, const char *  channel_name  )

extern

Sets the target event record channel name of the “event record channel buffer usage becomes greater/less than” trigger condition condition to channel_name.

Parameters

[in]	condition	“Event record channel buffer usage becomes greater/less than” trigger condition of which to set the target event record channel name.
[in]	channel_name	Target event record channel name of condition (copied).

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_BUFFER_USAGE_HIGH or LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW.
• channel_name is not NULL.

See also

lttng_condition_buffer_usage_get_channel_name() – Get the target event record channel name of a “event record channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_set_domain_type()

enum lttng_condition_status lttng_condition_buffer_usage_set_domain_type ( struct lttng_condition *  condition, enum lttng_domain_type  domain  )

extern

Sets the target tracing domain of the “event record channel buffer usage becomes greater/less than” trigger condition condition to domain.

Parameters

[in]	condition	“Event record channel buffer usage becomes greater/less than” trigger condition of which to set the target tracing domain.
[in]	domain	Target tracing domain 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_BUFFER_USAGE_HIGH or LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW.
• domain is not NULL.

See also

lttng_condition_buffer_usage_get_domain_type() – Get the target tracing domain of a “event record channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_set_session_name()

enum lttng_condition_status lttng_condition_buffer_usage_set_session_name ( struct lttng_condition *  condition, const char *  session_name  )

extern

Sets the target recording session name of the “event record channel buffer usage becomes greater/less than” trigger condition condition to session_name.

Parameters

[in]	condition	“Event record channel buffer usage becomes greater/less than” trigger condition of which to set the target recording session name.
[in]	session_name	Target recording session name of condition (copied).

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_BUFFER_USAGE_HIGH or LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW.
• session_name is not NULL.

See also

lttng_condition_buffer_usage_get_session_name() – Get the target recording session name of a “event record channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_set_threshold()

enum lttng_condition_status lttng_condition_buffer_usage_set_threshold ( struct lttng_condition *  condition, uint64_t  threshold  )

extern

Sets the \lt_obj_event record channel buffer usage size threshold of the “event record channel buffer usage becomes greater/less than” trigger condition condition to threshold.

This function overrides any current event record channel buffer usage threshold of condition.

Parameters

[in]	condition	“Event record channel buffer usage becomes greater/less than” trigger condition of which to set the event record channel buffer usage size threshold.
[in]	threshold	Event record channel buffer usage size (bytes) threshold 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_BUFFER_USAGE_HIGH or LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW.

See also

lttng_condition_buffer_usage_get_threshold() – Get the event record channel buffer usage size threshold of a “event record channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_set_threshold_ratio() – Set the event record channel buffer usage ratio threshold of a “event record channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_set_threshold_ratio()

enum lttng_condition_status lttng_condition_buffer_usage_set_threshold_ratio ( struct lttng_condition *  condition, double  threshold  )

extern

Sets the \lt_obj_event record channel buffer usage ratio threshold of the “event record channel buffer usage becomes greater/less than” trigger condition condition to threshold.

This function overrides any current event record channel buffer usage threshold of condition.

Parameters

[in]	condition	“Event record channel buffer usage becomes greater/less than” trigger condition of which to set the event record channel buffer usage ratio threshold.
[in]	threshold	Event record channel buffer usage ratio (between 0 and 1) threshold 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_BUFFER_USAGE_HIGH or LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW.

See also

lttng_condition_buffer_usage_get_threshold_ratio() – Get the event record channel buffer usage ratio threshold of a “event record channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_set_threshold() – Set the event record channel buffer usage size threshold of a “event record channel buffer usage becomes greater/less than” trigger condition.

lttng_evaluation_buffer_usage_get_usage()

enum lttng_evaluation_status lttng_evaluation_buffer_usage_get_usage ( const struct lttng_evaluation *  evaluation, uint64_t *  usage  )

extern

Sets *usage to the captured event record channel buffer usage size of the “event record channel buffer usage becomes greater/less than” trigger condition evaluation evaluation.

Parameters

[in]	evaluation	“Event record channel buffer usage becomes greater/less than” trigger condition evaluation of which to get the captured event record channel buffer usage size.
[out]	usage	On success, this function sets *usage to the captured event record channel buffer usage size (bytes) of evaluation.

Return values

LTTNG_EVALUATION_STATUS_OK	Success.
LTTNG_EVALUATION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• evaluation is not NULL.
• evaluation has the type LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH or LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW.
• usage is not NULL.

See also

lttng_evaluation_buffer_usage_get_usage_ratio() – Get the captured event record channel buffer usage ratio of a “event record channel buffer usage becomes greater/less than” trigger condition evaluation.

lttng_evaluation_buffer_usage_get_usage_ratio()

enum lttng_evaluation_status lttng_evaluation_buffer_usage_get_usage_ratio ( const struct lttng_evaluation *  evaluation, double *  usage  )

extern

Sets *usage to the captured event record channel buffer usage ratio of the “event record channel buffer usage becomes greater/less than” trigger condition evaluation evaluation.

Parameters

[in]	evaluation	“Event record channel buffer usage becomes greater/less than” trigger condition evaluation of which to get the captured event record channel buffer usage ratio.
[out]	usage	On success, this function sets *usage to the captured event record channel buffer usage ratio (between 0 and 1) of evaluation.

Return values

LTTNG_EVALUATION_STATUS_OK	Success.
LTTNG_EVALUATION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• evaluation is not NULL.
• evaluation has the type LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH or LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW.
• usage is not NULL.

See also

lttng_evaluation_buffer_usage_get_usage() – Get the captured event record channel buffer usage size of a “event record channel buffer usage becomes greater/less than” trigger condition evaluation.