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