Extend the rotation API to provide network trace archive locations

[lttng-tools.git] / include / lttng / rotation.h

diff --git a/include/lttng/rotation.h b/include/lttng/rotation.h
index 05216fc37629b7f29f7de657e2263112b0a572ab..dbc0183da7e856a26df927c454df439b2e5f3a37 100644 (file)
--- a/include/lttng/rotation.h
+++ b/include/lttng/rotation.h
@@ -20,6 +20,7 @@
 #define LTTNG_ROTATION_H
 
 #include <stdint.h>
+#include <lttng/location.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -29,15 +30,19 @@ extern "C" {
  * Return codes for lttng_rotation_handle_get_state()
  */
 enum lttng_rotation_state {
+       /*
+        * Session has not been rotated.
+        */
+       LTTNG_ROTATION_STATE_NO_ROTATION = 0,
        /*
         * Rotation is ongoing, but has not been completed yet.
         */
-       LTTNG_ROTATION_STATE_ONGOING = 0,
+       LTTNG_ROTATION_STATE_ONGOING = 1,
        /*
         * Rotation has been completed and the resulting chunk
         * can now safely be read.
         */
-       LTTNG_ROTATION_STATE_COMPLETED = 1,
+       LTTNG_ROTATION_STATE_COMPLETED = 2,
        /*
         * The rotation has expired.
         *
@@ -48,11 +53,11 @@ enum lttng_rotation_state {
         * Note that this state does not guarantee the the rotation was
         * completed successfully.
         */
-       LTTNG_ROTATION_STATE_EXPIRED = 2,
+       LTTNG_ROTATION_STATE_EXPIRED = 3,
        /*
         * The rotation could not be completed due to an error.
         */
-       LTTNG_ROTATION_STATE_ERROR = 3,
+       LTTNG_ROTATION_STATE_ERROR = 4,
 };
 
 enum lttng_rotation_status {
@@ -69,17 +74,16 @@ enum lttng_rotation_status {
  * Input parameter to the lttng_rotate_session command.
  *
  * An immediate rotation is performed as soon as possible by the tracers.
- *
- * The lttng_rotation_immediate_attr object is opaque to the user. Use the
- * helper functions below to access it.
  */
 struct lttng_rotation_immediate_attr;
 
+/*
+ * Input parameter to the lttng_rotate_schedule command.
+ */
+struct lttng_rotation_schedule_attr;
+
 /*
  * Handle used to represent a specific rotation.
- *
- * This object is opaque to the user. Use the helper functions below to access
- * it.
  */
 struct lttng_rotation_handle;
 
@@ -90,12 +94,25 @@ struct lttng_rotation_handle;
 extern struct lttng_rotation_immediate_attr *
 lttng_rotation_immediate_attr_create(void);
 
+/*
+ * Return a newly allocated scheduled rotate session descriptor object or NULL
+ * on error.
+ */
+extern struct lttng_rotation_schedule_attr *
+lttng_rotation_schedule_attr_create(void);
+
 /*
  * Destroy a given immediate session rotation descriptor object.
  */
 extern void lttng_rotation_immediate_attr_destroy(
                struct lttng_rotation_immediate_attr *attr);
 
+/*
+ * Destroy a given scheduled rotate session descriptor object.
+ */
+extern void lttng_rotation_schedule_attr_destroy(
+               struct lttng_rotation_schedule_attr *attr);
+
 /*
  * Set the name of the session to rotate immediately.
  *
@@ -106,6 +123,32 @@ extern enum lttng_rotation_status lttng_rotation_immediate_attr_set_session_name
                struct lttng_rotation_immediate_attr *attr,
                const char *session_name);
 
+/*
+ * Set the name of the session to rotate automatically.
+ *
+ * The session_name parameter is copied to the immediate session rotation
+ * attributes.
+ */
+extern enum lttng_rotation_status lttng_rotation_schedule_attr_set_session_name(
+               struct lttng_rotation_schedule_attr *attr,
+               const char *session_name);
+
+/*
+ * Set the timer to periodically rotate the session (µs, -1ULL to disable).
+ */
+extern enum lttng_rotation_status lttng_rotation_schedule_attr_set_timer_period(
+               struct lttng_rotation_schedule_attr *attr, uint64_t timer);
+
+/*
+ * Set the size to rotate the session (bytes, -1ULL to disable).
+ */
+void lttng_rotation_schedule_attr_set_size(
+               struct lttng_rotation_schedule_attr *attr, uint64_t size);
+
+/*
+ * lttng rotate session handle functions.
+ */
+
 /*
  * Get the current state of the rotation referenced by the handle.
  *
@@ -120,16 +163,14 @@ extern enum lttng_rotation_status lttng_rotation_handle_get_state(
  * Get the location of the rotation's resulting archive.
  *
  * The rotation must be completed in order for this call to succeed.
- * The path returned is owned by the rotation handle.
+ * The location returned remains owned by the rotation handle.
  *
- * Note that path will not be set in case of error, or if the session
- * rotation has expired.
- *
- * FIXME: Return an lttng_location object instead of a path.
+ * Note that location will not be set in case of error, or if the session
+ * rotation handle has expired.
  */
-extern enum lttng_rotation_status lttng_rotation_handle_get_completed_archive_location(
+extern enum lttng_rotation_status lttng_rotation_handle_get_archive_location(
                struct lttng_rotation_handle *rotation_handle,
-               const char **path);
+               const struct lttng_trace_archive_location **location);
 
 /*
  * Destroy an lttng_rotate_session handle.
@@ -150,6 +191,32 @@ extern void lttng_rotation_handle_destroy(
 extern int lttng_rotate_session(struct lttng_rotation_immediate_attr *attr,
                struct lttng_rotation_handle **rotation_handle);
 
+/*
+ * Configure a session to rotate periodically or based on the size written.
+ */
+extern int lttng_rotation_set_schedule(
+               struct lttng_rotation_schedule_attr *attr);
+
+/*
+ * Ask the sessiond for the value of the rotate timer (in micro-seconds) of the
+ * session.
+ *
+ * On success, return 0 and set the value or rotate_timer, on error return a
+ * negative value.
+ */
+extern int lttng_rotation_schedule_get_timer_period(const char *session_name,
+               uint64_t *rotate_timer);
+
+/*
+ * Ask the sessiond for the value of the rotate size (in micro-seconds) of the
+ * session.
+ *
+ * On success, return 0 and set the value or rotate_size, on error return
+ * a negative value.
+ */
+extern int lttng_rotation_schedule_get_size(const char *session_name,
+               uint64_t *rotate_size);
+
 #ifdef __cplusplus
 }
 #endif