“Recording session consumed data size becomes greater than” trigger condition API

Collaboration diagram for “Recording session consumed data size becomes greater than” trigger condition API:

Functions
struct lttng_condition *	lttng_condition_session_consumed_size_create (void)
	Creates an initial “recording session consumed data size becomes greater than” trigger condition to execute an action when the total consumed size of the tracing data of all the event record channels of a given recording session becomes greater than some configured threshold.
enum lttng_condition_status	lttng_condition_session_consumed_size_get_session_name (const struct lttng_condition *condition, const char **session_name)
	Sets *session_name to the target recording session name of the “recording session consumed data size becomes greater than” trigger condition condition.
enum lttng_condition_status	lttng_condition_session_consumed_size_get_threshold (const struct lttng_condition *condition, uint64_t *threshold)
	Sets *threshold to the total consumed size (bytes) threshold of the “recording session consumed data size becomes greater than” trigger condition condition.
enum lttng_condition_status	lttng_condition_session_consumed_size_set_session_name (struct lttng_condition *condition, const char *session_name)
	Sets the target recording session name of the “recording session consumed data size becomes greater than” trigger condition condition to session_name.
enum lttng_condition_status	lttng_condition_session_consumed_size_set_threshold (struct lttng_condition *condition, uint64_t threshold)
	Sets the total consumed size threshold of the “recording session consumed data size becomes greater than” trigger condition condition to threshold bytes.
enum lttng_evaluation_status	lttng_evaluation_session_consumed_size_get_consumed_size (const struct lttng_evaluation *evaluation, uint64_t *consumed_size)
	Sets *consumed_size to the captured total recording session consumed size of the “recording session consumed data size becomes greater than” trigger condition evaluation evaluation.

Detailed Description

A “recording session consumed data size becomes greater than” trigger condition is considered satisfied when the total consumed size of the tracing data of all the event record channels of a given recording session becomes greater than some configured threshold.

A “recording session consumed data size becomes greater than” trigger condition has the type LTTNG_CONDITION_TYPE_SESSION_CONSUMED_SIZE.

Every time the monitor timer of an event record channel expires, LTTng updates the statistics, like the total consumed tracing data size, of its owning recording session. This is when LTTng tries to evaluate “recording session consumed data size becomes greater than” conditions.

To create a valid “recording session consumed data size becomes greater than” trigger condition:

1. Create the initial trigger condition with lttng_condition_session_consumed_size_create().
2. Set a threshold (consumed bytes) with lttng_condition_session_consumed_size_set_threshold().
3. Set a target recording session name with lttng_condition_session_consumed_size_set_session_name().

Get the threshold of a “recording session consumed data size becomes greater than” trigger condition with lttng_condition_session_consumed_size_get_threshold().

Get the target recording session name of a “recording session consumed data size becomes greater than” trigger condition with lttng_condition_session_consumed_size_get_session_name().

Evaluation

When a trigger with a “recording session consumed data size becomes greater than” condition fires, LTTng captures the total consumed size. With the “notify” action, a user may then read the captured value from the condition evaluation with lttng_evaluation_session_consumed_size_get_consumed_size().

Function Documentation

lttng_condition_session_consumed_size_create()

struct lttng_condition * lttng_condition_session_consumed_size_create ( void  )

extern

Creates an initial “recording session consumed data size becomes greater than” trigger condition to execute an action when the total consumed size of the tracing data of all the event record channels of a given recording session 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_session_consumed_size_set_session_name().
• Set a total consumed size threshold with lttng_condition_session_consumed_size_set_threshold().

Returns

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

Destroy the returned trigger condition with lttng_condition_destroy().

lttng_condition_session_consumed_size_get_session_name()

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

extern

Sets *session_name to the target recording session name of the “recording session consumed data size becomes greater than” trigger condition condition.

Parameters

[in]	condition	“Recording session consumed data size becomes greater 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_SESSION_CONSUMED_SIZE.
• session_name is not NULL.

See also

lttng_condition_session_consumed_size_set_session_name() – Set the target recording session name of a “recording session consumed data size becomes greater than” trigger condition.

lttng_condition_session_consumed_size_get_threshold()

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

extern

Sets *threshold to the total consumed size (bytes) threshold of the “recording session consumed data size becomes greater than” trigger condition condition.

Parameters

[in]	condition	“Recording session consumed data size becomes greater than” trigger condition of which to get the total consumed size threshold.
[out]	threshold	On success, this function sets *threshold to the total consumed size (bytes) of condition.

Return values

LTTNG_CONDITION_STATUS_OK	Success.
LTTNG_CONDITION_STATUS_UNSET	condition has no total consumed size threshold.
LTTNG_CONDITION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• condition is not NULL.
• condition has the type LTTNG_CONDITION_TYPE_SESSION_CONSUMED_SIZE.
• threshold is not NULL.

See also

lttng_condition_session_consumed_size_set_threshold() – Set the total consumed size threshold of a “recording session consumed data size becomes greater than” trigger condition.

lttng_condition_session_consumed_size_set_session_name()

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

extern

Sets the target recording session name of the “recording session consumed data size becomes greater than” trigger condition condition to session_name.

Parameters

[in]	condition	“Recording session consumed data size becomes greater 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_SESSION_CONSUMED_SIZE.
• session_name is not NULL.

See also

lttng_condition_session_consumed_size_get_session_name() – Get the target recording session name of a “recording session consumed data size becomes greater than” trigger condition.

lttng_condition_session_consumed_size_set_threshold()

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

extern

Sets the total consumed size threshold of the “recording session consumed data size becomes greater than” trigger condition condition to threshold bytes.

Parameters

[in]	condition	“Recording session consumed data size becomes greater than” trigger condition of which to set the total consumed size threshold.
[in]	threshold	Total consumed 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_SESSION_CONSUMED_SIZE.

See also

lttng_condition_session_consumed_size_get_threshold() – Get the total consumed size threshold of a “recording session consumed data size becomes greater than” trigger condition.

lttng_evaluation_session_consumed_size_get_consumed_size()

enum lttng_evaluation_status lttng_evaluation_session_consumed_size_get_consumed_size ( const struct lttng_evaluation *  evaluation, uint64_t *  consumed_size  )

extern

Sets *consumed_size to the captured total recording session consumed size of the “recording session consumed data size becomes greater than” trigger condition evaluation evaluation.

Parameters

[in]	evaluation	“Recording session consumed data size becomes greater than” trigger condition evaluation of which to get the captured total recording session consumed size.
[out]	consumed_size	On success, this function sets *consumed_size to the captured total recording session consumed 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_SESSION_CONSUMED_SIZE.
• consumed_size is not NULL.