Hi everyone, This is the initial RFC for snapshot in lttng-tools. Once accepted, it will be available in "doc/proposals/0006-lttng-snapshot.txt".
Any questions, comments or fixes are VERY welcome. There are probably English mistakes so feel free to point it out to me. Thanks! David
RFC - LTTng snapshot Author: David Goulet <[email protected]> Version: - v0.1: 11/04/2013 * Initial proposal Motivation ---------- This proposal is for the snapshot feature in lttng-tools. The idea is to be able to snapshot a portion of the trace and write it to a specified output (disk or network). This could be particularly useful with in flight recorder mode where you detect a problem on your system for instance and then use this snapshot feature to save the latest buffers which should contain informations to help understand the issue. Requirements ----------------- In order to snapshot a session, it must be set in flight recorder mode meaning that there is *no* consumer extracting the trace and writing it to a destination. To do that, the --no-output option is added to "lttng create" command. $ lttng create --no-output Create a session with active tracing but no data being collected. For the API call lttng_create_session(), simply set the URL to NULL. Furthermore, by default, this command will set all subsequent channel in overwrite mode. You can force the discard value (overwrite=0) but it is a bit pointless since the snapshot does NOT remove the data from the buffers. Proposed Solution ----------------- First, the lttng command line UI new command is presented followed by the new API calls. Unlike the other lttng command, this one uses the git alike UI but in the form of the object first and action after where previous command only use action such as "enable-event". $ lttng snapshot [ACTION] [OPTIONS] ACTION: (detailed below) The user can specify an output destination either for the current session (being the default) or on the spot when the command is executed. To specify an output for the session, use the "add-output" action. $ lttng snapshot add-output [URL] [OPTIONS] OPTIONS: -s, --session NAME -C, --ctrl-url URL -D, --data-url URL -a, --alias ALIAS Name of the output in the session. Without the -s, the current session is used. The above command adds an output location to the session so when a snapshot is recorded later on, it's sent there. This action command takes either a valid lttng URL (see proposal 0004) or the -C/-D options from "lttng create" can be used to define relayd on different ports. The alias option can be used to give a name to the output so it's recognizable in the list command and can also be used with the del command. Following that, two new actions are available to control outputs. You can list and delete outputs. $ lttng snapshot list-output [1]: file://[...] [2]: net://1.1.1.1:8762:9123 [3] - ALIAS: file://[...] $ lttng snapshot del-output ID|ALIAS The output identified by the ID or alias is removed from the session. In this case the ID is the number returned by list-output (e.g.: 2). To specify an output destination on the spot when the snapshot is taken, use the record action. $ lttng snapshot record [URL] [OPTIONS] OPTIONS: -s, --session NAME Session name -n, --name NAME Name of the snapshot to recognize it afterwards. -m, --max-size SIZE Maximum bytes size of the snapshot. No URL means that the default output of the session is used. The max-size is the maximum size of the trace you want to snapshot. The name is used so you can recognize the snapshot once taken and written on disk. Finally, the -s let the user specify a session name. Finally, we allow the snapshot command to be used without an action which basically do "lttng snapshot record". $ lttng snapshot [OPTIONS] OPTIONS: -s, --session NAME -m, --max-size SIZE Maximum bytes size of the snapshot. $ lttng snapshot -s mysession -m 8192 Snapshot the session and puts it in the session define output directory. By default, the snapshot(s) are saved in the session directory in the snapshot/ directory. SESSION_DIR/snapshot/<name>-<date>-<time>/[...] Public API ---------- /* * Snapshot output structure. Padding will be added once this RFC is accepted. */ struct lttng_snapshot_output { int id; uint64_t max_size; /* 0: unlimited. */ char alias[NAME_MAX]; char url[PATH_MAX]; }; /* * Return the ID of the output or a negative value being a LTTNG_ERR* code. */ int lttng_snapshot_add_output(struct lttng_handle *handle, struct lttng_snapshot_output *output); /* * Return 0 on success or else a negative LTTNG_ERR* code. */ int lttng_snapshot_del_output(int id, char *alias); /* * Return the number of output and set outputs with the returned info. * * On error, a negative LTTNG_ERR* code is returned. */ ssize_t lttng_snapshot_list_output(struct lttng_handle *handle, struct lttng_snapshot_output **outputs); /* * If output is specified, use it as output only for this snapshot or else if * NULL, the default snapshot destination of the session is used. If name is * specified, write it in <name>-<date>-<time> or else if name is NULL, only * the date and time will be used for the directory name. * * This is a blocking call meaning that it will return only if the snapshot is * completed. For now, no-wait is not supported by we keep a parameter for that * future case. The wait param is ignored. * * Return 0 on success or else a negative LTTNG_ERR* code. */ int lttng_snapshot_record(struct lttng_handle *handle, struct lttng_snapshot_output *output, char *name, int wait);
_______________________________________________ lttng-dev mailing list [email protected] http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev
