Commit | Line | Data |
---|---|---|
878d7519 JG |
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. |