doc/man: put short option's argument too
[lttng-tools.git] / doc / proposals / 0006-lttng-snapshot.txt
1 RFC - LTTng snapshot
2
3 Author: David Goulet <dgoulet@efficios.com>
4
5 Version:
6 - v0.1: 11/04/2013
7 * Initial proposal
8
9 Motivation
10 ----------
11
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.
18
19 Requirements
20 -----------------
21
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"
25 command.
26
27 $ lttng create --no-output
28 Create a session with active tracing but no data being collected.
29
30 For the API call lttng_create_session(), simply set the URL to NULL.
31
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.
35
36 Proposed Solution
37 -----------------
38
39 First, the new lttng command line UI is presented followed by the new API
40 calls.
41
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
44 "enable-event".
45
46 $ lttng snapshot [ACTION] [OPTIONS]
47
48 ACTION: (detailed below)
49
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.
53
54 $ lttng snapshot add-output [URL] [OPTIONS]
55
56 OPTIONS:
57 -s, --session NAME
58 -C, --ctrl-url URL
59 -D, --data-url URL
60 -a, --alias ALIAS Name of the output in the session.
61 -m, --max-size SIZE Maximum bytes size of the snapshot.
62
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
69 command.
70
71 Following that, two new actions are available to control outputs. You can list
72 and delete outputs.
73
74 $ lttng snapshot list-output
75 [1]: file://[...]
76 [2]: net://1.1.1.1:8762:9123
77 [3] - ALIAS: file://[...]
78
79 $ lttng snapshot del-output ID|ALIAS
80
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).
83
84 To specify an output destination on the spot when the snapshot is taken, use
85 the record action.
86
87 $ lttng snapshot record [URL] [OPTIONS]
88
89 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.
93 -C, --ctrl-url URL
94 -D, --data-url URL
95
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).
100
101 Finally, we allow the snapshot command to be used without an action which
102 basically do "lttng snapshot record".
103
104 $ lttng snapshot [OPTIONS]
105
106 OPTIONS:
107 -s, --session NAME
108 -m, --max-size SIZE Maximum bytes size of the snapshot.
109
110 $ lttng snapshot -s mysession -m 8192
111
112 Snapshot the session and puts it in the session define output directory.
113
114 By default, the snapshot(s) are saved in the session directory in the snapshot/ directory.
115
116 SESSION_DIR/snapshot/<name>-<date>-<time>/[...]
117
118 Public API
119 ----------
120
121 /*
122 * Snapshot output structure. Padding will be added once this RFC is accepted.
123 */
124 struct lttng_snapshot_output {
125 int id;
126 uint64_t max_size; /* 0: unlimited. */
127 char alias[NAME_MAX];
128 char url[PATH_MAX];
129 };
130
131 /*
132 * Return the ID of the output or a negative value being a LTTNG_ERR* code.
133 */
134 int lttng_snapshot_add_output(struct lttng_handle *handle,
135 struct lttng_snapshot_output *output);
136
137 /*
138 * Return 0 on success or else a negative LTTNG_ERR* code.
139 */
140 int lttng_snapshot_del_output(int id, char *alias);
141
142 /*
143 * Return the number of output and set outputs with the returned info.
144 *
145 * On error, a negative LTTNG_ERR* code is returned.
146 */
147 ssize_t lttng_snapshot_list_output(struct lttng_handle *handle,
148 struct lttng_snapshot_output **outputs);
149
150 /*
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.
155 *
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.
159 *
160 * Return 0 on success or else a negative LTTNG_ERR* code.
161 */
162 int lttng_snapshot_record(struct lttng_handle *handle,
163 struct lttng_snapshot_output *output,
164 char *name, int wait);
This page took 0.033662 seconds and 4 git commands to generate.