| 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); |