| 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. |