From 878d75191d8882b616e5a1eaf40e542818759828 Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=A9mie=20Galarneau?= Date: Thu, 5 Dec 2013 14:52:31 -0500 Subject: [PATCH] Add daemon and session configuration save/restore RFC MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Jérémie Galarneau Signed-off-by: David Goulet --- doc/proposals/0007-save-restore.txt | 197 ++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 doc/proposals/0007-save-restore.txt diff --git a/doc/proposals/0007-save-restore.txt b/doc/proposals/0007-save-restore.txt new file mode 100644 index 000000000..4f33cb13f --- /dev/null +++ b/doc/proposals/0007-save-restore.txt @@ -0,0 +1,197 @@ +RFC - LTTng session and daemon configuration save and restore + +Author: Jérémie Galarneau + +Version: + - v0.2: 04/12/2013 + * Reorganized the text following David Goulet's recommendations + - v0.1: 03/12/2013 + * Initial proposal + +Introduction +------------- + +This proposal details the file formats, LTTng APIs and command line interfaces +used to save and restore session and daemon configurations. + + +Daemon Configuration File Format +-------------------------------- + +The LTTng session and relay daemons shall be configurable using INI +configuration files. The set of configuration options accepted by LTTng daemons +corresponds to the command line options available for each daemon. + +The sections in the files must match the daemons' names: [sessiond] and +[relayd]. The entries under each section must match the long option names +supported by the daemons. Options specified on the command line shall always +have precedence over options set by the configuration files. + +An example demonstrating the use of such configuration +options follows. + +[sessiond] +consumerd32-path=/lib/lttng/libexec/lttng-consumerd +consumerd64-path=/lib64/lttng/libexec/lttng-consumerd +no-kernel=1 + +[relayd] +data-port=tcp://0.0.0.0:5343 +output=/tmp/MyTraces + +Daemon configuration files are, by default, either stored system-wide under +/etc/lttng/*.conf or in the user's home directory under $HOME/.lttng/*.conf. + +New options may be added to the daemon configuration file as features are +added to the relay and session daemons. The daemons shall ignore unrecognized +options to ensure forward compatibility. + + +LTTng Command Line - Daemon Configuration +----------------------------------------- + +On launch, the session, relay and consumer daemons will search for files with +the .conf extension in the following folders, in order of precedence: + 1) Any path specified using a new --load-config option + 2) $HOME/.lttng/*.conf + 3) /etc/lttng/*.conf + + +Session Configuration File Format +--------------------------------- + +The LTTng session configuration file format must enable the serialization of the +session, channel and event structures of the LTTng API. Since these concepts +are eminently hierarchical, it only makes sense to use a file format that can +express such relationships. + +While an INI based file format was the first considered, for its ease of use +and human readability, it appears that INI provides no standard way of +expressing hierarchies. It is, of course, possible to flatten session/channel +hierarchies using prefixed section names, but this is both error prone and +unsupported by most INI file reading libraries. This means that we would have +to code our own INI handling code and produce a specification to document our +additions to the INI format. INI also provides no standard versioning mechanism. + +In keeping with the desire to use a human-readable format, we have considered +rolling our own format. This format could express hierarchy using tabulations +to delimit scopes, not unlike the Python language. Such a format would be both +relatively easy to parse, but also readable. However, this both requires +documenting the format in a specification, rolling our own parsing and +validation code, thus losing the benefit of reusing external libraries. This +option has the highest maintenance cost considering the amount of code and +documentation to be produced while presenting marginal benefits over the INI +approach. + +Finally, it seems that using a standard hierarchical format such as JSON or +XML would be the most appropriate choice. Both of these formats have intrinsic +support for representation of hierarchical relationships. They also benefit from +having a lot of hardened external libraries that will provide parsing, +validation and write support. This is a huge advantage from both +maintainability and interoperability standpoints. However, both formats +present the disadvantage of being harder, although minimally, to edit manually. +It remains to be seen if manual editing of session configurations really is an +important use-case. Using lttng's save feature would probably prove more +convenient than editing the files manually. Furthermore, the addition of a +"dry-run" option to the lttng client would significantly alleviate this pain +point. + +XML seems like a better option than JSON since it makes it possible to have +robust file validation using a pre-defined schema. The use of version-specific +schemas could also be beneficial for backward compatibility as the format +moves forward. Finally, character encoding handling is already a solved +problem for most XML libraries. + + +LTTng ABI/API +------------- + +Two new functions are added to the lttng.h API. + +int lttng_load_sessions(const char *url, const char *session_name, + int flags/struct lttng_session_load_attr *attr); + +Load sessions. If url is a directory, all .lttng files it contains will be +loaded. If session_name is NULL, all sessions found in url are restored. +If a session_name is provided, only this session will be restored. + +A supplementary argument, either a "flags" argument or an attribute structure, +is used to indicate whether or not the sessions currently known to the +session daemon should be replaced by the ones found in the configuration +file(s), provided that their names are the same. +Even though this is the only current use-case for this argument, a structure +with a reasonable amount of padding may be more suitable than a primary +type to accommodate new features. Thoughts? + + +int lttng_save_sessions(const char *url, const char *session_name, + int flags/struct lttng_session_save_attr *attr); + +Save sessions. If url is a directory, the session configuration will be saved +as session_name.lttng. If a complete file name is provided, the session(s) to be +saved will be written to this file. If session_name is NULL, all sessions +currently known to the session daemon will be saved. If a name is provided, only +that session will be saved. + +The reasoning for the flags/attr argument is the same as for the +lttng_load_sessions() function, but for a configuration file overwrite +option. + + +LTTng Command Line - Session Configuration +------------------------------------------ + +Tracing session configurations can be saved and restored using the lttng command +line client. This capability introduces two new command line options. + + +-- Load session configurations -- + +$ lttng load -s SESSION_NAME [OPTIONS] + +Loads tracing session configurations. + +.lttng files will be searched in the following default paths, in order of +precedence: + 1) $(HOME)/.lttng/sessions + 2) /etc/lttng/sessions + +A session name or the -a option must be passed as the SESSION_NAME argument. +Like some other lttng commands, such as enable-event, the -a option stands for +"all". If this option is used, every session found in the paths will be loaded. + +If a session was saved as active, the tracing for that session will be activated +automatically on load. The current session configuration of the session daemon +is also preserved when a configuration is loaded. The new session configurations +are added to the current session set. + +Tracing sessions saved in an active state will be resumed on load. + +--input-path, -i +Path in which to search for SESSION_NAME's description. If the path is a +directory, all .lttng files it contains will be opened and searched for +SESSION_NAME. If an input path is provided, the -a option will load all +session configurations found in this path. The default paths are ignored when +this option is used. + +--force, -f +If a restored session's name conflicts with a currently existing session, the +original session configuration is preserved. However, if the --force option is +used, the restored session takes precedence. The original session will be +destroyed. + + +-- Save session configurations -- + +$ lttng save -s SESSION_NAME [OPTIONS] + +Saves tracing configurations. + +The selected tracing session's configuration will be saved in the +$HOME/.lttng/sessions folder. If the -a option is used, every session known +to the session daemon will be saved. + +--output-path, -o +If the provided output path is a directory, the session will be saved in a +file named "SESSION_NAME.lttng". However, if the path is a file, the session(s) +will all be saved in the same file. -- 2.34.1