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