3 Author: David Goulet <dgoulet@efficios.com>
12 This proposal is for the snapshot feature in lttng-tools. The idea is to be
13 able to snapshot a portion of the trace and write it to a specified output
14 (disk or network). This could be particularly useful in flight recorder mode
15 where you detect a problem on your system for instance and then use this
16 snapshot feature to save the latest buffers which should contain information to
17 help understand the issue.
22 In order to snapshot a session, it must be set in flight recorder mode meaning
23 that there is *no* consumer extracting the trace and writing it to a
24 destination. To do that, the --no-output option is added to "lttng create"
27 $ lttng create --no-output
28 Create a session with active tracing but no data being collected.
30 For the API call lttng_create_session(), simply set the URL to NULL.
32 Furthermore, by default, this command will set all subsequent channel in
33 overwrite mode. You can force the discard value (overwrite=0) but it is a bit
34 pointless since the snapshot does NOT remove the data from the buffers.
39 First, the new lttng command line UI is presented followed by the new API
42 This new command uses a git-alike UI, but in the form of the object first
43 followed by the desired action, whereas other commands only use actions such as
46 $ lttng snapshot [ACTION] [OPTIONS]
48 ACTION: (detailed below)
50 The user can specify an output destination either for the current session
51 (being the default) or on the spot when the command is executed. To specify an
52 output for the session, use the "add-output" action.
54 $ lttng snapshot add-output [URL] [OPTIONS]
60 -a, --alias ALIAS Name of the output in the session.
61 -m, --max-size SIZE Maximum bytes size of the snapshot.
63 Without the -s, the current session is used. The above command adds an output
64 location to the session so when a snapshot is recorded later on, it's sent
65 there. This action command takes either a valid lttng URL (see proposal 0004)
66 or the -C/-D options from "lttng create" can be used to define relayd on
67 different ports. The alias option can be used to give a name to the output so
68 it's recognizable in the list command and can also be used with the del
71 Following that, two new actions are available to control outputs. You can list
74 $ lttng snapshot list-output
76 [2]: net://1.1.1.1:8762:9123
77 [3] - ALIAS: file://[...]
79 $ lttng snapshot del-output ID|ALIAS
81 The output identified by the ID or alias is removed from the session. In
82 this case the ID is the number returned by list-output (e.g.: 2).
84 To specify an output destination on the spot when the snapshot is taken, use
87 $ lttng snapshot record [URL] [OPTIONS]
90 -s, --session NAME Session name
91 -n, --name NAME Name of the snapshot to recognize it afterwards.
92 -m, --max-size SIZE Maximum bytes size of the snapshot.
96 No URL means that the default output of the session is used. The max-size is
97 the maximum size of the trace you want to snapshot. The name is used so you can
98 recognize the snapshot once taken and written on disk. Finally, the -s let the
99 user specify a session name or else the current session is used (in .lttngrc).
101 Finally, we allow the snapshot command to be used without an action which
102 basically do "lttng snapshot record".
104 $ lttng snapshot [OPTIONS]
108 -m, --max-size SIZE Maximum bytes size of the snapshot.
110 $ lttng snapshot -s mysession -m 8192
112 Snapshot the session and puts it in the session define output directory.
114 By default, the snapshot(s) are saved in the session directory in the snapshot/ directory.
116 SESSION_DIR/snapshot/<name>-<date>-<time>/[...]
122 * Snapshot output structure. Padding will be added once this RFC is accepted.
124 struct lttng_snapshot_output {
126 uint64_t max_size; /* 0: unlimited. */
127 char alias[NAME_MAX];
132 * Return the ID of the output or a negative value being a LTTNG_ERR* code.
134 int lttng_snapshot_add_output(struct lttng_handle *handle,
135 struct lttng_snapshot_output *output);
138 * Return 0 on success or else a negative LTTNG_ERR* code.
140 int lttng_snapshot_del_output(int id, char *alias);
143 * Return the number of output and set outputs with the returned info.
145 * On error, a negative LTTNG_ERR* code is returned.
147 ssize_t lttng_snapshot_list_output(struct lttng_handle *handle,
148 struct lttng_snapshot_output **outputs);
151 * If output is specified, use it as output only for this snapshot or else if
152 * NULL, the default snapshot destination of the session is used. If name is
153 * specified, write it in <name>-<date>-<time> or else if name is NULL, only
154 * the date and time will be used for the directory name.
156 * This is a blocking call meaning that it will return only if the snapshot is
157 * completed or an error occurred. For now, no-wait is not supported but we keep
158 * a parameter for that future case. The wait param is ignored.
160 * Return 0 on success or else a negative LTTNG_ERR* code.
162 int lttng_snapshot_record(struct lttng_handle *handle,
163 struct lttng_snapshot_output *output,
164 char *name, int wait);