“Channel buffer usage becomes greater/less than” trigger condition API

Collaboration diagram for “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 channel name of the “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 “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 “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 channel buffer usage size (bytes) threshold of the “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 channel buffer usage ratio threshold of the “channel buffer usage becomes greater/less than” trigger condition condition.
struct lttng_condition *	lttng_condition_buffer_usage_high_create (void)
	Creates an initial “channel buffer usage becomes greater than” trigger condition to execute an action when the ring buffer usage of a given channel becomes greater than some configured threshold.
struct lttng_condition *	lttng_condition_buffer_usage_low_create (void)
	Creates an initial “channel buffer usage becomes less than” trigger condition to execute an action when the ring buffer usage of a given 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 channel name of the “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 “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 “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 channel buffer usage size threshold of the “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 channel buffer usage ratio threshold of the “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 channel buffer usage size of the “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 channel buffer usage ratio of the “channel buffer usage becomes greater/less than” trigger condition evaluation evaluation.

Detailed Description

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

A “channel buffer usage becomes greater than” trigger condition has the type LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH.

A “channel buffer usage becomes less than” trigger condition has the type LTTNG_CONDITION_TYPE_BUFFER_USAGE_LOW.

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

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

1. Create the initial trigger condition with one of:

   Channel buffer usage becomes greater than

   lttng_condition_buffer_usage_high_create()

   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 channel name with lttng_condition_buffer_usage_set_channel_name().

Get the buffer usage threshold of a “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 channel name of a “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 a “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 channel name of the “channel buffer usage becomes greater/less than” trigger condition condition.

Parameters

[in]	condition	“Channel buffer usage becomes greater/less than” trigger condition of which to get the target channel name.
[out]	channel_name	On success, this function sets *channel_name to the target 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 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 channel name of a “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 “channel buffer usage becomes greater/less than” trigger condition condition.

Parameters

[in]	condition	“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 “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 “channel buffer usage becomes greater/less than” trigger condition condition.

Parameters

[in]	condition	“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 “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 channel buffer usage size (bytes) threshold of the “channel buffer usage becomes greater/less than” trigger condition condition.

Parameters

[in]	condition	“Channel buffer usage becomes greater/less than” trigger condition of which to get the 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 channel buffer usage size threshold, although it may have a 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 channel buffer usage size threshold of a “channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_get_threshold_ratio() – Get the channel buffer usage ratio threshold of a “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 channel buffer usage ratio threshold of the “channel buffer usage becomes greater/less than” trigger condition condition.

Parameters

[in]	condition	“Channel buffer usage becomes greater/less than” trigger condition of which to get the channel buffer usage ratio threshold.
[out]	threshold	On success, this function sets *threshold to the 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 channel buffer usage ratio threshold, although it may have a 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 channel buffer usage ratio threshold of a “channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_get_threshold() – Get the channel buffer usage size threshold of a “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 “channel buffer usage becomes greater than” trigger condition to execute an action when the ring buffer usage of a given 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 channel name with lttng_condition_buffer_usage_set_channel_name().
• Set a 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 “channel buffer usage becomes less than” trigger condition to execute an action when the ring buffer usage of a given 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 channel name with lttng_condition_buffer_usage_set_channel_name().
• Set a 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 channel name of the “channel buffer usage becomes greater/less than” trigger condition condition to channel_name.

Parameters

[in]	condition	“Channel buffer usage becomes greater/less than” trigger condition of which to set the target channel name.
[in]	channel_name	Target 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 channel name of a “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 “channel buffer usage becomes greater/less than” trigger condition condition to domain.

Parameters

[in]	condition	“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 “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 “channel buffer usage becomes greater/less than” trigger condition condition to session_name.

Parameters

[in]	condition	“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 “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 channel buffer usage size threshold of the “channel buffer usage becomes greater/less than” trigger condition condition to threshold.

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

Parameters

[in]	condition	“Channel buffer usage becomes greater/less than” trigger condition of which to set the channel buffer usage size threshold.
[in]	threshold	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 channel buffer usage size threshold of a “channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_set_threshold_ratio() – Set the channel buffer usage ratio threshold of a “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 channel buffer usage ratio threshold of the “channel buffer usage becomes greater/less than” trigger condition condition to threshold.

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

Parameters

[in]	condition	“Channel buffer usage becomes greater/less than” trigger condition of which to set the channel buffer usage ratio threshold.
[in]	threshold	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 channel buffer usage ratio threshold of a “channel buffer usage becomes greater/less than” trigger condition.

lttng_condition_buffer_usage_set_threshold() – Set the channel buffer usage size threshold of a “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 channel buffer usage size of the “channel buffer usage becomes greater/less than” trigger condition evaluation evaluation.

Parameters

[in]	evaluation	“Channel buffer usage becomes greater/less than” trigger condition evaluation of which to get the captured channel buffer usage size.
[out]	usage	On success, this function sets *usage to the captured 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 channel buffer usage ratio of a “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 channel buffer usage ratio of the “channel buffer usage becomes greater/less than” trigger condition evaluation evaluation.

Parameters

[in]	evaluation	“Channel buffer usage becomes greater/less than” trigger condition evaluation of which to get the captured channel buffer usage ratio.
[out]	usage	On success, this function sets *usage to the captured 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 channel buffer usage size of a “channel buffer usage becomes greater/less than” trigger condition evaluation.