include/lttng/condition/session-rotation.h

   1 /*
   2  * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_CONDITION_SESSION_ROTATION_H
   9 #define LTTNG_CONDITION_SESSION_ROTATION_H
  10
  11 #include <lttng/condition/evaluation.h>
  12 #include <lttng/condition/condition.h>
  13 #include <stdint.h>
  14 #include <lttng/domain.h>
  15 #include <lttng/location.h>
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif
  20
  21 /**
  22  * Session rotation conditions allow an action to be taken whenever a
  23  * session rotation is ongoing or completed.
  24  *
  25  * Session rotation conditions have the following properties:
  26  *   - the exact name of the session to be monitored for rotations
  27  *
  28  * Wildcards, regular expressions or other globbing mechanisms are not supported
  29  * in session rotation condition properties.
  30  */
  31
  32 /*
  33  * Create a newly allocated session rotation in progress condition.
  34  *
  35  * A session rotation ongoing condition evaluates to true whenever a rotation
  36  * is ongoing for a given session.
  37  *
  38  * Returns a new condition on success, NULL on failure. This condition must be
  39  * destroyed using lttng_condition_destroy().
  40  */
  41 extern struct lttng_condition *
  42 lttng_condition_session_rotation_ongoing_create(void);
  43
  44 /*
  45  * Create a newly allocated session rotation completion condition.
  46  *
  47  * A session rotation completed condition evaluates to true whenever a rotation
  48  * is completed for a given session. This condition is not evaluated on
  49  * subscription or registration of a trigger. This means that a trigger
  50  * using this condition will only fire when the next session rotation completes.
  51  * Previously completed rotations will have no effect.
  52  *
  53  * Returns a new condition on success, NULL on failure. This condition must be
  54  * destroyed using lttng_condition_destroy().
  55  */
  56  extern struct lttng_condition *
  57  lttng_condition_session_rotation_completed_create(void);
  58
  59 /*
  60  * Get the session name property of a session rotation condition.
  61  *
  62  * The caller does not assume the ownership of the returned session name. The
  63  * session name shall only only be used for the duration of the condition's
  64  * lifetime, or before a different session name is set.
  65  *
  66  * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's session
  67  * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
  68  * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a session name
  69  * was not set prior to this call.
  70  */
  71 extern enum lttng_condition_status
  72 lttng_condition_session_rotation_get_session_name(
  73                 const struct lttng_condition *condition,
  74                 const char **session_name);
  75
  76 /*
  77  * Set the session name property of a session rotation condition.
  78  *
  79  * The passed session name parameter will be copied to the condition.
  80  *
  81  * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
  82  * if invalid paramenters are passed.
  83  */
  84 extern enum lttng_condition_status
  85 lttng_condition_session_rotation_set_session_name(
  86                 struct lttng_condition *condition,
  87                 const char *session_name);
  88
  89 /**
  90  * lttng_evaluation_session_rotation are specialised lttng_evaluations
  91  * which allow users to query a number of properties resulting from the
  92  * evaluation of a condition which evaluated to true.
  93  */
  94
  95 /*
  96  * Get the session rotation id property of a session rotation evaluation.
  97  *
  98  * Returns LTTNG_EVALUATION_STATUS_OK on success and the id of the session
  99  * rotation, or LTTNG_EVALUATION_STATUS_INVALID if an invalid parameter is
 100  * passed.
 101  */
 102 extern enum lttng_evaluation_status
 103 lttng_evaluation_session_rotation_get_id(
 104                 const struct lttng_evaluation *evaluation, uint64_t *id);
 105
 106 /*
 107  * Get the session rotation location property of a session rotation completed
 108  * evaluation.
 109  *
 110  * The caller does not assume the ownership of the returned location. The
 111  * location shall only only be used for the duration of the evaluation's
 112  * lifetime.
 113  *
 114  * Returns LTTNG_EVALUATION_STATUS_OK and set location on success.
 115  * A NULL location may be returned if a rotation chunk's location
 116  * has expired.
 117  *
 118  * LTTNG_EVALUATION_STATUS_INVALID is returned if an invalid parameter is
 119  * passed.
 120  */
 121 extern enum lttng_evaluation_status
 122 lttng_evaluation_session_rotation_completed_get_location(
 123                 const struct lttng_evaluation *evaluation,
 124                 const struct lttng_trace_archive_location **location);
 125
 126 #ifdef __cplusplus
 127 }
 128 #endif
 129
 130 #endif /* LTTNG_CONDITION_SESSION_ROTATION_H */