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