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/condition.h>
  12 #include <lttng/condition/evaluation.h>
  13 #include <lttng/domain.h>
  14 #include <lttng/location.h>
  15 #include <lttng/lttng-export.h>
  16
  17 #include <stdint.h>
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 /**
  24  * Session rotation conditions allow an action to be taken whenever a
  25  * session rotation is ongoing or completed.
  26  *
  27  * Session rotation conditions have the following properties:
  28  *   - the exact name of the session to be monitored for rotations
  29  *
  30  * Wildcards, regular expressions or other globbing mechanisms are not supported
  31  * in session rotation condition properties.
  32  */
  33
  34 /*
  35  * Create a newly allocated session rotation in progress condition.
  36  *
  37  * A session rotation ongoing condition evaluates to true whenever a rotation
  38  * is ongoing for a given session.
  39  *
  40  * Returns a new condition on success, NULL on failure. This condition must be
  41  * destroyed using lttng_condition_destroy().
  42  */
  43 LTTNG_EXPORT extern struct lttng_condition *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 *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 LTTNG_EXPORT extern enum lttng_condition_status
  72 lttng_condition_session_rotation_get_session_name(const struct lttng_condition *condition,
  73                                                   const char **session_name);
  74
  75 /*
  76  * Set the session name property of a session rotation condition.
  77  *
  78  * The passed session name parameter will be copied to the condition.
  79  *
  80  * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
  81  * if invalid paramenters are passed.
  82  */
  83 LTTNG_EXPORT extern enum lttng_condition_status
  84 lttng_condition_session_rotation_set_session_name(struct lttng_condition *condition,
  85                                                   const char *session_name);
  86
  87 /**
  88  * lttng_evaluation_session_rotation are specialised lttng_evaluations
  89  * which allow users to query a number of properties resulting from the
  90  * evaluation of a condition which evaluated to true.
  91  */
  92
  93 /*
  94  * Get the session rotation id property of a session rotation evaluation.
  95  *
  96  * Returns LTTNG_EVALUATION_STATUS_OK on success and the id of the session
  97  * rotation, or LTTNG_EVALUATION_STATUS_INVALID if an invalid parameter is
  98  * passed.
  99  */
 100 LTTNG_EXPORT extern enum lttng_evaluation_status
 101 lttng_evaluation_session_rotation_get_id(const struct lttng_evaluation *evaluation, uint64_t *id);
 102
 103 /*
 104  * Get the session rotation location property of a session rotation completed
 105  * evaluation.
 106  *
 107  * The caller does not assume the ownership of the returned location. The
 108  * location shall only only be used for the duration of the evaluation's
 109  * lifetime.
 110  *
 111  * Returns LTTNG_EVALUATION_STATUS_OK and set location on success.
 112  * A NULL location may be returned if a rotation chunk's location
 113  * has expired.
 114  *
 115  * LTTNG_EVALUATION_STATUS_INVALID is returned if an invalid parameter is
 116  * passed.
 117  */
 118 LTTNG_EXPORT extern enum lttng_evaluation_status
 119 lttng_evaluation_session_rotation_completed_get_location(
 120         const struct lttng_evaluation *evaluation,
 121         const struct lttng_trace_archive_location **location);
 122
 123 #ifdef __cplusplus
 124 }
 125 #endif
 126
 127 #endif /* LTTNG_CONDITION_SESSION_ROTATION_H */