Trigger action rate policy API

Collaboration diagram for Trigger action rate policy API:

Data Structures
struct	lttng_rate_policy
	Trigger action rate policy (opaque type). More...

Enumerations
enum	lttng_rate_policy_status { LTTNG_RATE_POLICY_STATUS_OK , LTTNG_RATE_POLICY_STATUS_INVALID , LTTNG_RATE_POLICY_STATUS_ERROR , LTTNG_RATE_POLICY_STATUS_UNKNOWN , LTTNG_RATE_POLICY_STATUS_UNSET , LTTNG_RATE_POLICY_STATUS_UNSUPPORTED , LTTNG_RATE_POLICY_STATUS_PERMISSION_DENIED }
	Return type of trigger action rate policy API functions. More...
enum	lttng_rate_policy_type { LTTNG_RATE_POLICY_TYPE_EVERY_N , LTTNG_RATE_POLICY_TYPE_ONCE_AFTER_N , LTTNG_RATE_POLICY_TYPE_UNKNOWN }
	Trigger action rate policy type. More...

Functions
void	lttng_rate_policy_destroy (struct lttng_rate_policy *policy)
	Destroys the trigger action rate policy policy.
struct lttng_rate_policy *	lttng_rate_policy_every_n_create (uint64_t n)
	Creates an “every N times” trigger action rate policy, setting N to n.
enum lttng_rate_policy_status	lttng_rate_policy_every_n_get_interval (const struct lttng_rate_policy *policy, uint64_t *n)
	Sets *n to N of the “every N times” trigger action rate policy policy.
enum lttng_rate_policy_type	lttng_rate_policy_get_type (const struct lttng_rate_policy *policy)
	Returns the type of the trigger action rate policy policy.
struct lttng_rate_policy *	lttng_rate_policy_once_after_n_create (uint64_t n)
	Creates a “once after N times” trigger action rate policy, setting N to n.
enum lttng_rate_policy_status	lttng_rate_policy_once_after_n_get_threshold (const struct lttng_rate_policy *policy, uint64_t *n)
	Sets *n to N of the “once after N times” trigger action rate policy policy.

Detailed Description

A trigger which fires (its condition is satisfied) leads to an execution request for its action. If its action is an action list, then LTTng creates an execution request for each action of the list, in order.

An execution request of a given action A first increments the execution request count C of A. The rate policy of A dictates how frequently A is allowed to execute relative to C.

In other words, the rate policy of a trigger action determines whether and when an execution request becomes an actual execution.

As of LTTng-tools 16.2, the available trigger action rate policies are:

Rate policy	Description	Type enumerator	Creation function
“Every N times”	LTTng executes A every time C is a multiple of N.	LTTNG_RATE_POLICY_TYPE_EVERY_N	lttng_rate_policy_every_n_create()
“Once after N times”	LTTng executes A a single time, when C is greater than or equal to N.	LTTNG_RATE_POLICY_TYPE_ONCE_AFTER_N	lttng_rate_policy_once_after_n_create()

Get the type of a trigger action rate policy with lttng_rate_policy_get_type().

Destroy a trigger action rate policy with lttng_rate_policy_destroy().

Set the rate policy of a trigger action with the following functions, depending on the action type:

Trigger action type	Rate policy setter
LTTNG_ACTION_TYPE_NOTIFY	lttng_action_notify_set_rate_policy()
LTTNG_ACTION_TYPE_START_SESSION	lttng_action_start_session_set_rate_policy()
LTTNG_ACTION_TYPE_STOP_SESSION	lttng_action_stop_session_set_rate_policy()
LTTNG_ACTION_TYPE_ROTATE_SESSION	lttng_action_rotate_session_set_rate_policy()
LTTNG_ACTION_TYPE_SNAPSHOT_SESSION	lttng_action_snapshot_session_set_rate_policy()

As of LTTng-tools 16.2, you cannot change the rate policy of an “increment map value” action: its effective rate policy is “every time”.

Enumeration Type Documentation

lttng_rate_policy_status

enum lttng_rate_policy_status

Return type of trigger action rate policy API functions.

Enumerator
LTTNG_RATE_POLICY_STATUS_OK	Success.
LTTNG_RATE_POLICY_STATUS_INVALID	Unsatisfied precondition.

lttng_rate_policy_type

enum lttng_rate_policy_type

Trigger action rate policy type.

Get the type of a trigger action rate policy with lttng_rate_policy_get_type().

Enumerator
LTTNG_RATE_POLICY_TYPE_EVERY_N	Every N times.
LTTNG_RATE_POLICY_TYPE_ONCE_AFTER_N	Once after N times.
LTTNG_RATE_POLICY_TYPE_UNKNOWN	Unknown (error).

Function Documentation

lttng_rate_policy_destroy()

void lttng_rate_policy_destroy ( struct lttng_rate_policy *  policy )

extern

Destroys the trigger action rate policy policy.

Parameters

[in]

policy

Trigger action rate policy to destroy. May be NULL.

lttng_rate_policy_every_n_create()

struct lttng_rate_policy * lttng_rate_policy_every_n_create ( uint64_t  n )

extern

Creates an “every N times” trigger action rate policy, setting N to n.

Parameters

[in]

n

Value of N.

Returns

Trigger action rate policy with the type LTTNG_RATE_POLICY_TYPE_EVERY_N on success, or NULL on error.

Destroy the returned rate policy with lttng_rate_policy_destroy().

lttng_rate_policy_every_n_get_interval()

enum lttng_rate_policy_status lttng_rate_policy_every_n_get_interval ( const struct lttng_rate_policy *  policy, uint64_t *  n  )

extern

Sets *n to N of the “every N times” trigger action rate policy policy.

Parameters

[in]	policy	“Every N times” trigger action rate policy of which to get N.
[out]	n	On success, this function sets *n to N.

Return values

LTTNG_RATE_POLICY_STATUS_OK	Success.
LTTNG_RATE_POLICY_STATUS_INVALID	Unsatisfied precondition.

Precondition

• policy is not NULL.
• policy has the type LTTNG_RATE_POLICY_TYPE_EVERY_N.
• n is not NULL.

lttng_rate_policy_get_type()

enum lttng_rate_policy_type lttng_rate_policy_get_type ( const struct lttng_rate_policy *  policy )

extern

Returns the type of the trigger action rate policy policy.

Parameters

[in]

policy

Trigger action rate policy of which to get the type.

Returns

Type of policy.

Precondition

• policy is not NULL.

lttng_rate_policy_once_after_n_create()

struct lttng_rate_policy * lttng_rate_policy_once_after_n_create ( uint64_t  n )

extern

Creates a “once after N times” trigger action rate policy, setting N to n.

Parameters

[in]

n

Value of N.

Returns

Trigger action rate policy with the type LTTNG_RATE_POLICY_TYPE_ONCE_AFTER_N on success, or NULL on error.

Destroy the returned rate policy with lttng_rate_policy_destroy().

lttng_rate_policy_once_after_n_get_threshold()

enum lttng_rate_policy_status lttng_rate_policy_once_after_n_get_threshold ( const struct lttng_rate_policy *  policy, uint64_t *  n  )

extern

Sets *n to N of the “once after N times” trigger action rate policy policy.

Parameters

[in]	policy	“Once after N times” trigger action rate policy of which to get N.
[out]	n	On success, this function sets *n to N.

Return values

LTTNG_RATE_POLICY_STATUS_OK	Success.
LTTNG_RATE_POLICY_STATUS_INVALID	Unsatisfied precondition.

Precondition

• policy is not NULL.
• policy has the type LTTNG_RATE_POLICY_TYPE_ONCE_AFTER_N.
• n is not NULL.