doc/proposals/0007-save-restore.txt

   1 RFC - LTTng session and daemon configuration save and restore
   2
   3 Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
   4
   5 Version:
   6         - v0.2: 04/12/2013
   7                 * Reorganized the text following David Goulet's recommendations
   8         - v0.1: 03/12/2013
   9                 * Initial proposal
  10
  11 Introduction
  12 -------------
  13
  14 This proposal details the file formats, LTTng APIs and command line interfaces
  15 used to save and restore session and daemon configurations.
  16
  17
  18 Daemon Configuration File Format
  19 --------------------------------
  20
  21 The LTTng session and relay daemons shall be configurable using INI
  22 configuration files. The set of configuration options accepted by LTTng daemons
  23 corresponds to the command line options available for each daemon.
  24
  25 The sections in the files must match the daemons' names: [sessiond] and
  26 [relayd]. The entries under each section must match the long option names
  27 supported by the daemons. Options specified on the command line shall always
  28 have precedence over options set by the configuration files.
  29
  30 An example demonstrating the use of such configuration
  31 options follows.
  32
  33 [sessiond]
  34 consumerd32-path=/lib/lttng/libexec/lttng-consumerd
  35 consumerd64-path=/lib64/lttng/libexec/lttng-consumerd
  36 no-kernel=1
  37
  38 [relayd]
  39 data-port=tcp://0.0.0.0:5343
  40 output=/tmp/MyTraces
  41
  42 Daemon configuration files are, by default, either stored system-wide under
  43 /etc/lttng/*.conf or in the user's home directory under $HOME/.lttng/*.conf.
  44
  45 New options may be added to the daemon configuration file as features are
  46 added to the relay and session daemons. The daemons shall ignore unrecognized
  47 options to ensure forward compatibility.
  48
  49
  50 LTTng Command Line - Daemon Configuration
  51 -----------------------------------------
  52
  53 On launch, the session, relay and consumer daemons will search for files with
  54 the .conf extension in the following folders, in order of precedence:
  55         1) Any path specified using a new --load-config option
  56         2) $HOME/.lttng/*.conf
  57         3) /etc/lttng/*.conf
  58
  59
  60 Session Configuration File Format
  61 ---------------------------------
  62
  63 The LTTng session configuration file format must enable the serialization of the
  64 session, channel and event structures of the LTTng API. Since these concepts
  65 are eminently hierarchical, it only makes sense to use a file format that can
  66 express such relationships.
  67
  68 While an INI based file format was the first considered, for its ease of use
  69 and human readability, it appears that INI provides no standard way of
  70 expressing hierarchies. It is, of course, possible to flatten session/channel
  71 hierarchies using prefixed section names, but this is both error prone and
  72 unsupported by most INI file reading libraries. This means that we would have
  73 to code our own INI handling code and produce a specification to document our
  74 additions to the INI format. INI also provides no standard versioning mechanism.
  75
  76 In keeping with the desire to use a human-readable format, we have considered
  77 rolling our own format. This format could express hierarchy using tabulations
  78 to delimit scopes, not unlike the Python language. Such a format would be both
  79 relatively easy to parse, but also readable. However, this both requires
  80 documenting the format in a specification, rolling our own parsing and
  81 validation code, thus losing the benefit of reusing external libraries. This
  82 option has the highest maintenance cost considering the amount of code and
  83 documentation to be produced while presenting marginal benefits over the INI
  84 approach.
  85
  86 Finally, it seems that using a standard hierarchical format such as JSON or
  87 XML would be the most appropriate choice. Both of these formats have intrinsic
  88 support for representation of hierarchical relationships. They also benefit from
  89 having a lot of hardened external libraries that will provide parsing,
  90 validation and write support. This is a huge advantage from both
  91 maintainability and interoperability standpoints. However, both formats
  92 present the disadvantage of being harder, although minimally, to edit manually.
  93 It remains to be seen if manual editing of session configurations really is an
  94 important use-case. Using lttng's save feature would probably prove more
  95 convenient than editing the files manually. Furthermore, the addition of a
  96 "dry-run" option to the lttng client would significantly alleviate this pain
  97 point.
  98
  99 XML seems like a better option than JSON since it makes it possible to have
 100 robust file validation using a pre-defined schema. The use of version-specific
 101 schemas could also be beneficial for backward compatibility as the format
 102 moves forward. Finally, character encoding handling is already a solved
 103 problem for most XML libraries.
 104
 105
 106 LTTng ABI/API
 107 -------------
 108
 109 Two new functions are added to the lttng.h API.
 110
 111 int lttng_load_sessions(const char *url, const char *session_name,
 112         int flags/struct lttng_session_load_attr *attr);
 113
 114 Load sessions. If url is a directory, all .lttng files it contains will be
 115 loaded. If session_name is NULL, all sessions found in url are restored.
 116 If a session_name is provided, only this session will be restored.
 117
 118 A supplementary argument, either a "flags" argument or an attribute structure,
 119 is used to indicate whether or not the sessions currently known to the
 120 session daemon should be replaced by the ones found in the configuration
 121 file(s), provided that their names are the same.
 122 Even though this is the only current use-case for this argument, a structure
 123 with a reasonable amount of padding may be more suitable than a primary
 124 type to accommodate new features. Thoughts?
 125
 126
 127 int lttng_save_sessions(const char *url, const char *session_name,
 128         int flags/struct lttng_session_save_attr *attr);
 129
 130 Save sessions. If url is a directory, the session configuration will be saved
 131 as session_name.lttng. If a complete file name is provided, the session(s) to be
 132 saved will be written to this file. If session_name is NULL, all sessions
 133 currently known to the session daemon will be saved. If a name is provided, only
 134 that session will be saved.
 135
 136 The reasoning for the flags/attr argument is the same as for the
 137 lttng_load_sessions() function, but for a configuration file overwrite
 138 option.
 139
 140
 141 LTTng Command Line - Session Configuration
 142 ------------------------------------------
 143
 144 Tracing session configurations can be saved and restored using the lttng command
 145 line client. This capability introduces two new command line options.
 146
 147
 148 -- Load session configurations --
 149
 150 $ lttng load -s SESSION_NAME [OPTIONS]
 151
 152 Loads tracing session configurations.
 153
 154 .lttng files will be searched in the following default paths, in order of
 155 precedence:
 156         1) $(HOME)/.lttng/sessions
 157         2) /etc/lttng/sessions
 158
 159 A session name or the -a option must be passed as the SESSION_NAME argument.
 160 Like some other lttng commands, such as enable-event, the -a option stands for
 161 "all". If this option is used, every session found in the paths will be loaded.
 162
 163 If a session was saved as active, the tracing for that session will be activated
 164 automatically on load. The current session configuration of the session daemon
 165 is also preserved when a configuration is loaded. The new session configurations
 166 are added to the current session set.
 167
 168 Tracing sessions saved in an active state will be resumed on load.
 169
 170 --input-path, -i
 171 Path in which to search for SESSION_NAME's description. If the path is a
 172 directory, all .lttng files it contains will be opened and searched for
 173 SESSION_NAME. If an input path is provided, the -a option will load all
 174 session configurations found in this path. The default paths are ignored when
 175 this option is used.
 176
 177 --force, -f
 178 If a restored session's name conflicts with a currently existing session, the
 179 original session configuration is preserved. However, if the --force option is
 180 used, the restored session takes precedence. The original session will be
 181 destroyed.
 182
 183
 184 -- Save session configurations --
 185
 186 $ lttng save -s SESSION_NAME [OPTIONS]
 187
 188 Saves tracing configurations.
 189
 190 The selected tracing session's configuration will be saved in the
 191 $HOME/.lttng/sessions folder. If the -a option is used, every session known
 192 to the session daemon will be saved.
 193
 194 --output-path, -o
 195 If the provided output path is a directory, the session will be saved in a
 196 file named "SESSION_NAME.lttng". However, if the path is a file, the session(s)
 197 will all be saved in the same file.