“Recording session rotation starts/finishes” trigger condition API

Collaboration diagram for “Recording session rotation starts/finishes” trigger condition API:

Functions
struct lttng_condition *	lttng_condition_session_rotation_completed_create (void)
	Creates an initial “recording session rotation finishes” trigger condition to execute an action when the rotation operation of a given recording session finishes.
enum lttng_condition_status	lttng_condition_session_rotation_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 rotation starts/finishes” trigger condition condition.
struct lttng_condition *	lttng_condition_session_rotation_ongoing_create (void)
	Creates an initial “recording session rotation starts” trigger condition to execute an action when the rotation operation of a given recording session starts.
enum lttng_condition_status	lttng_condition_session_rotation_set_session_name (struct lttng_condition *condition, const char *session_name)
	Sets the target recording session name of the “recording session rotation starts/finishes” trigger condition condition to session_name.
enum lttng_evaluation_status	lttng_evaluation_session_rotation_completed_get_location (const struct lttng_evaluation *evaluation, const struct lttng_trace_archive_location **location)
	Sets *location to the captured resulting trace chunk archive location of the “recording session rotation finishes” trigger condition evaluation evaluation.
enum lttng_evaluation_status	lttng_evaluation_session_rotation_get_id (const struct lttng_evaluation *evaluation, uint64_t *id)
	Sets *id to the recording session rotation ID of the “recording session rotation starts/finishes” trigger condition evaluation evaluation.

Detailed Description

A “recording session rotation starts/finishes” trigger condition is considered satisfied when the rotation operation of a given recording session starts or finishes.

A “recording session rotation starts” trigger condition has the type LTTNG_CONDITION_TYPE_SESSION_ROTATION_ONGOING.

A “recording session rotation finishes” trigger condition has the type LTTNG_CONDITION_TYPE_SESSION_ROTATION_COMPLETED.

To create a valid “recording session rotation starts/finishes” trigger condition:

1. Create the initial trigger condition with one of:

   Recording session rotation starts

   lttng_condition_session_rotation_ongoing_create()

   Recording session rotation finishes

   lttng_condition_session_rotation_completed_create()

2. Set a target recording session name with lttng_condition_buffer_usage_set_session_name().

Get the target recording session name of a “recording session rotation starts/finishes” trigger condition with lttng_condition_session_rotation_get_session_name().

Evaluation

When a trigger with a “recording session rotation starts/finishes” condition fires, LTTng captures the recording session rotation ID. Moreover, when a “recording session rotation finishes” condition fires, LTTng captures the resulting trace archive location. With the “notify” action, a user may then read the captured value(s) from the condition evaluation with lttng_evaluation_session_rotation_get_id() and lttng_evaluation_session_rotation_completed_get_location().

Function Documentation

lttng_condition_session_rotation_completed_create()

struct lttng_condition * lttng_condition_session_rotation_completed_create ( void  )

extern

Creates an initial “recording session rotation finishes” trigger condition to execute an action when the rotation operation of a given recording session finishes.

On success, the returned trigger condition isn't valid yet; you must set a target recording session name with lttng_condition_session_rotation_set_session_name().

Returns

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

Destroy the returned trigger condition with lttng_condition_destroy().

lttng_condition_session_rotation_get_session_name()

enum lttng_condition_status lttng_condition_session_rotation_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 rotation starts/finishes” trigger condition condition.

Parameters

[in]	condition	“Recording session rotation starts/finishes” 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_ROTATION_ONGOING or LTTNG_CONDITION_TYPE_SESSION_ROTATION_COMPLETED.
• session_name is not NULL.

See also

lttng_condition_session_rotation_set_session_name() – Set the target recording session name of a “recording session rotation starts/finishes” trigger condition.

lttng_condition_session_rotation_ongoing_create()

struct lttng_condition * lttng_condition_session_rotation_ongoing_create ( void  )

extern

Creates an initial “recording session rotation starts” trigger condition to execute an action when the rotation operation of a given recording session starts.

On success, the returned trigger condition isn't valid yet; you must set a target recording session name with lttng_condition_session_rotation_set_session_name().

Returns

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

Destroy the returned trigger condition with lttng_condition_destroy().

lttng_condition_session_rotation_set_session_name()

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

extern

Sets the target recording session name of the “recording session rotation starts/finishes” trigger condition condition to session_name.

Parameters

[in]	condition	“Recording session rotation starts/finishes” 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_ROTATION_ONGOING or LTTNG_CONDITION_TYPE_SESSION_ROTATION_COMPLETED.
• session_name is not NULL.

See also

lttng_condition_session_rotation_get_session_name() – Get the target recording session name of a “recording session rotation starts/finishes” trigger condition.

lttng_evaluation_session_rotation_completed_get_location()

enum lttng_evaluation_status lttng_evaluation_session_rotation_completed_get_location ( const struct lttng_evaluation *  evaluation, const struct lttng_trace_archive_location **  location  )

extern

Sets *location to the captured resulting trace chunk archive location of the “recording session rotation finishes” trigger condition evaluation evaluation.

Parameters

[in]	evaluation	“Recording session rotation finishes” trigger condition evaluation of which to get the captured resulting trace chunk archive location.
[out]	location	On success, this function sets *location to the captured resulting trace chunk archive location of evaluation. This function may also set *location to NULL if the trace chunk archive location has expired.

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_ROTATION_COMPLETED.
• location is not NULL.

lttng_evaluation_session_rotation_get_id()

enum lttng_evaluation_status lttng_evaluation_session_rotation_get_id ( const struct lttng_evaluation *  evaluation, uint64_t *  id  )

extern

Sets *id to the recording session rotation ID of the “recording session rotation starts/finishes” trigger condition evaluation evaluation.

Parameters

[in]	evaluation	“Recording session rotation starts/finishes” trigger condition evaluation of which to get the captured recording session rotation ID.
[out]	id	On success, this function sets *id to the captured recording session rotation ID 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_ROTATION_ONGOING or LTTNG_CONDITION_TYPE_SESSION_ROTATION_COMPLETED.
• id is not NULL.