X-Git-Url: http://git.efficios.com/?p=lttng-tools.git;a=blobdiff_plain;f=include%2Flttng%2Frotation.h;h=316f2cdb52c5700e5dd42dd409d910cbd98f04f5;hp=9b797ac11c2783256c420f1cd70b22da08c835bd;hb=403e01ee4af47ae897fe42f1ed420648027022ae;hpb=259c267446a63c501298f39a5d2397314b11f729 diff --git a/include/lttng/rotation.h b/include/lttng/rotation.h index 9b797ac11..316f2cdb5 100644 --- a/include/lttng/rotation.h +++ b/include/lttng/rotation.h @@ -1,25 +1,16 @@ /* - * Copyright (C) 2017 - Julien Desfossez - * Copyright (C) 2018 - Jérémie Galarneau + * Copyright (C) 2017 Julien Desfossez + * Copyright (C) 2018 Jérémie Galarneau * - * This library is free software; you can redistribute it and/or modify it - * under the terms of the GNU Lesser General Public License, version 2.1 only, - * as published by the Free Software Foundation. + * SPDX-License-Identifier: LGPL-2.1-only * - * This library is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License - * for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this library; if not, write to the Free Software Foundation, - * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ #ifndef LTTNG_ROTATION_H #define LTTNG_ROTATION_H #include +#include #ifdef __cplusplus extern "C" { @@ -29,15 +20,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 +43,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 = -1, }; enum lttng_rotation_status { @@ -63,19 +58,33 @@ enum lttng_rotation_status { LTTNG_ROTATION_STATUS_ERROR = -1, /* Invalid parameters provided. */ LTTNG_ROTATION_STATUS_INVALID = -2, + /* A schedule of this type is already set. */ + LTTNG_ROTATION_STATUS_SCHEDULE_ALREADY_SET = -3, + /* No such rotation schedule set. */ + LTTNG_ROTATION_STATUS_SCHEDULE_NOT_SET = -3, +}; + +enum lttng_rotation_schedule_type { + LTTNG_ROTATION_SCHEDULE_TYPE_UNKNOWN = -1, + LTTNG_ROTATION_SCHEDULE_TYPE_SIZE_THRESHOLD = 0, + LTTNG_ROTATION_SCHEDULE_TYPE_PERIODIC = 1, }; /* - * Input parameter to the lttng_rotate_session command. - * - * An immediate rotation is performed as soon as possible by the tracers. + * Descriptor of an immediate session rotation to be performed as soon as + * possible by the tracers. */ -struct lttng_rotation_immediate_attr; +struct lttng_rotation_immediate_descriptor; /* - * Input parameter to the lttng_rotate_schedule command. + * Session rotation schedule to add to a session. */ -struct lttng_rotation_schedule_attr; +struct lttng_rotation_schedule; + +/* + * A set of lttng_rotation_schedule objects. + */ +struct lttng_rotation_schedules; /* * Handle used to represent a specific rotation. @@ -83,110 +92,178 @@ struct lttng_rotation_schedule_attr; struct lttng_rotation_handle; /* - * Return a newly allocated immediate session rotation descriptor object or NULL - * on error. + * lttng rotate session handle functions. */ -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. + * Get the current state of the rotation referenced by the handle. + * + * This will issue a request to the session daemon on every call. Hence, + * the result of this call may change over time. */ -extern struct lttng_rotation_schedule_attr * -lttng_rotation_schedule_attr_create(void); +extern enum lttng_rotation_status lttng_rotation_handle_get_state( + struct lttng_rotation_handle *rotation_handle, + enum lttng_rotation_state *rotation_state); /* - * Destroy a given immediate session rotation descriptor object. + * Get the location of the rotation's resulting archive. + * + * The rotation must be completed in order for this call to succeed. + * The location returned remains owned by the rotation handle. + * + * Note that location will not be set in case of error, or if the session + * rotation handle has expired. */ -extern void lttng_rotation_immediate_attr_destroy( - struct lttng_rotation_immediate_attr *attr); +extern enum lttng_rotation_status lttng_rotation_handle_get_archive_location( + struct lttng_rotation_handle *rotation_handle, + const struct lttng_trace_archive_location **location); /* - * Destroy a given scheduled rotate session descriptor object. + * Destroy an lttng_rotate_session handle. */ -extern void lttng_rotation_schedule_attr_destroy( - struct lttng_rotation_schedule_attr *attr); +extern void lttng_rotation_handle_destroy( + struct lttng_rotation_handle *rotation_handle); /* - * Set the name of the session to rotate immediately. + * Rotate the output folder of the session. + * + * On success, handle is allocated and can be used to monitor the progress + * of the rotation with lttng_rotation_get_state(). The handle must be freed + * by the caller with lttng_rotation_handle_destroy(). * - * The session_name parameter is copied to the immediate session rotation - * attributes. + * Passing NULL as the immediate rotation descriptor results in the default + * options being used. + * + * Return 0 if the rotate action was successfully launched or a negative + * LTTng error code on error. */ -extern enum lttng_rotation_status lttng_rotation_immediate_attr_set_session_name( - struct lttng_rotation_immediate_attr *attr, - const char *session_name); +extern int lttng_rotate_session(const char *session_name, + struct lttng_rotation_immediate_descriptor *descriptor, + struct lttng_rotation_handle **rotation_handle); /* - * Set the name of the session to rotate automatically. + * Get the type of a rotation schedule object. + */ +extern enum lttng_rotation_schedule_type lttng_rotation_schedule_get_type( + const struct lttng_rotation_schedule *schedule); + +/* + * Return a newly allocated size-based session rotation schedule or NULL on + * error. + */ +extern struct lttng_rotation_schedule * +lttng_rotation_schedule_size_threshold_create(void); + +/* + * Get a session rotation schedule's size threshold. * - * The session_name parameter is copied to the immediate session rotation - * attributes. + * Returns LTTNG_ROTATION_STATUS_OK on success. + * LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset. */ -extern enum lttng_rotation_status lttng_rotation_schedule_attr_set_session_name( - struct lttng_rotation_schedule_attr *attr, - const char *session_name); +extern enum lttng_rotation_status +lttng_rotation_schedule_size_threshold_get_threshold( + const struct lttng_rotation_schedule *schedule, + uint64_t *size_threshold_bytes); /* - * Set the timer to periodically rotate the session (µs, -1ULL to disable). + * Set a session rotation schedule's size threshold. */ -extern enum lttng_rotation_status lttng_rotation_schedule_attr_set_timer_period( - struct lttng_rotation_schedule_attr *attr, uint64_t timer); +extern enum lttng_rotation_status +lttng_rotation_schedule_size_threshold_set_threshold( + struct lttng_rotation_schedule *schedule, + uint64_t size_threshold_bytes); /* - * lttng rotate session handle functions. + * Return a newly allocated periodic session rotation schedule or NULL on + * error. */ +extern struct lttng_rotation_schedule * +lttng_rotation_schedule_periodic_create(void); /* - * Get the current state of the rotation referenced by the handle. + * Get a time-based session rotation schedule's period. * - * This will issue a request to the session daemon on every call. Hence, - * the result of this call may change over time. + * Returns LTTNG_ROTATION_STATUS_OK on success. + * LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset. */ -extern enum lttng_rotation_status lttng_rotation_handle_get_state( - struct lttng_rotation_handle *rotation_handle, - enum lttng_rotation_state *rotation_state); +extern enum lttng_rotation_status lttng_rotation_schedule_periodic_get_period( + const struct lttng_rotation_schedule *schedule, + uint64_t *period_us); /* - * 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. + * Set a time-based session rotation schedule's period. + */ +extern enum lttng_rotation_status lttng_rotation_schedule_periodic_set_period( + struct lttng_rotation_schedule *schedule, + uint64_t period_us); + +/* + * Destroy a rotation schedule. + */ +extern void lttng_rotation_schedule_destroy( + struct lttng_rotation_schedule *schedule); + +/* + * Destroy a set of rotation schedules. Pointers to any schedule contained + * in this set become invalid after this call. + */ +extern void lttng_rotation_schedules_destroy( + struct lttng_rotation_schedules *schedules); + +/* + * Get the number of schedules in a schedule set. + */ +extern enum lttng_rotation_status lttng_rotation_schedules_get_count( + const struct lttng_rotation_schedules *schedules, + unsigned int *count); + +/* + * Get a schedule from the set at a given index. * - * Note that path will not be set in case of error, or if the session - * rotation has expired. + * Note that the set maintains the ownership of the returned schedule. + * It must not be destroyed by the user, nor should it be held beyond + * the lifetime of the schedules set. * - * FIXME: Return an lttng_location object instead of a path. + * Returns a rotation schedule, or NULL on error. */ -extern enum lttng_rotation_status lttng_rotation_handle_get_completed_archive_location( - struct lttng_rotation_handle *rotation_handle, - const char **path); +extern const struct lttng_rotation_schedule * +lttng_rotation_schedules_get_at_index( + const struct lttng_rotation_schedules *schedules, + unsigned int index); /* - * Destroy an lttng_rotate_session handle. + * Add a session rotation schedule to a session. + * + * Note that the current implementation currently limits the rotation schedules + * associated to a given session to one per type. + * + * Returns LTTNG_ROTATION_STATUS_OK on success, + * LTTNG_ROTATION_STATUS_SCHEDULE_ALREADY_SET if a rotation of the same type + * is already set. */ -extern void lttng_rotation_handle_destroy( - struct lttng_rotation_handle *rotation_handle); +extern enum lttng_rotation_status lttng_session_add_rotation_schedule( + const char *session_name, + const struct lttng_rotation_schedule *schedule); /* - * Rotate the output folder of the session - * - * On success, handle is allocated and can be used to monitor the progress - * of the rotation with lttng_rotation_get_state(). The handle must be freed - * by the caller with lttng_rotation_handle_destroy(). + * Remove a session rotation schedule from a session. * - * Return 0 if the rotate action was successfully launched or a negative - * LTTng error code on error. + * Returns LTTNG_ROTATION_STATUS_OK on success, + * LTTNG_ROTATION_STATUS_SCHEDULE_INVALID if the provided schedule is + * not set. */ -extern int lttng_rotate_session(struct lttng_rotation_immediate_attr *attr, - struct lttng_rotation_handle **rotation_handle); +extern enum lttng_rotation_status lttng_session_remove_rotation_schedule( + const char *session_name, + const struct lttng_rotation_schedule *schedule); /* - * Configure a session to rotate periodically or based on the size written. + * Get the rotation schedules associated with a given session. + * + * Returns LTTNG_OK on success, or a negative lttng error code on error. */ -extern int lttng_rotation_set_schedule( - struct lttng_rotation_schedule_attr *attr); +extern int lttng_session_list_rotation_schedules( + const char *session_name, + struct lttng_rotation_schedules **schedules); #ifdef __cplusplus }