include/lttng/condition/session-rotation.h

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