| | 1 | lttng-snapshot(1) |
| | 2 | ================= |
| | 3 | :revdate: 9 November 2018 |
| | 4 | |
| | 5 | |
| | 6 | NAME |
| | 7 | ---- |
| | 8 | lttng-snapshot - Take LTTng snapshots and configure snapshot outputs |
| | 9 | |
| | 10 | |
| | 11 | SYNOPSIS |
| | 12 | -------- |
| | 13 | Add a snapshot output: |
| | 14 | |
| | 15 | [verse] |
| | 16 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot add-output* [option:--max-size='SIZE'] |
| | 17 | [option:--name='NAME'] [option:--session='SESSION'] |
| | 18 | (option:--ctrl-url='URL' option:--data-url='URL' | 'URL') |
| | 19 | |
| | 20 | Remove a snapshot output: |
| | 21 | |
| | 22 | [verse] |
| | 23 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot del-output* [option:--session='SESSION'] |
| | 24 | ('ID' | 'NAME') |
| | 25 | |
| | 26 | List current snapshot outputs: |
| | 27 | |
| | 28 | [verse] |
| | 29 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot list-output* [option:--session='SESSION'] |
| | 30 | |
| | 31 | Take a snapshot: |
| | 32 | |
| | 33 | [verse] |
| | 34 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot record* [option:--max-size='SIZE'] |
| | 35 | [option:--name='NAME'] [option:--session='SESSION'] |
| | 36 | (option:--ctrl-url='URL' option:--data-url='URL' | 'URL') |
| | 37 | |
| | 38 | |
| | 39 | DESCRIPTION |
| | 40 | ----------- |
| | 41 | The `lttng snapshot` command manages the snapshot outputs and takes |
| | 42 | snapshots. |
| | 43 | |
| | 44 | A _snapshot_ is a dump of the current sub-buffers of all the channels |
| | 45 | of a given tracing session. When a snapshot is taken, the memory dump |
| | 46 | is sent to the registered snapshot outputs. |
| | 47 | |
| | 48 | The tracing session should be created in _snapshot mode_ to make sure |
| | 49 | taking snapshots is allowed. This is done at tracing session creation |
| | 50 | time using the man:lttng-create(1) command. |
| | 51 | |
| | 52 | Note that, when a snapshot is taken, the sub-buffers are not cleared. |
| | 53 | This means that different recorded snapshots may contain the same |
| | 54 | events. |
| | 55 | |
| | 56 | |
| | 57 | Snapshot outputs |
| | 58 | ~~~~~~~~~~~~~~~~ |
| | 59 | Snapshot outputs are the destinations of snapshot files when a |
| | 60 | snapshot is taken using the `record` action. |
| | 61 | |
| | 62 | As of this version, only one snapshot output is allowed. |
| | 63 | |
| | 64 | A snapshot output can be added using the `add-output` action. The |
| | 65 | output destination URL is set using either the 'URL' positional |
| | 66 | argument, or both the option:--ctrl-url and option:--data-url options. |
| | 67 | See man:lttng-create(1) to learn more about the URL format. |
| | 68 | |
| | 69 | A name can be assigned to an output when adding it using the |
| | 70 | option:--name option. This name is part of the names of the |
| | 71 | snapshot files written to this output. |
| | 72 | |
| | 73 | By default, the snapshot files can be as big as the sum of the |
| | 74 | sizes of all the sub-buffers or all the channels of the selected |
| | 75 | tracing session. The maximum total size of all the snapshot files can |
| | 76 | be configured using the option:--max-size option. |
| | 77 | |
| | 78 | Snapshot outputs can be listed using the `list-output` action. |
| | 79 | |
| | 80 | Snapshot outputs can be removed using the `del-output` action. The |
| | 81 | configured name can be used when removing an output, or an ID as |
| | 82 | listed by the `list-output` action. |
| | 83 | |
| | 84 | |
| | 85 | Taking a snapshot |
| | 86 | ~~~~~~~~~~~~~~~~~ |
| | 87 | Taking a snapshot of the current tracing session is as easy as: |
| | 88 | |
| | 89 | [role="term"] |
| | 90 | ---- |
| | 91 | $ lttng snapshot record |
| | 92 | ---- |
| | 93 | |
| | 94 | This writes the snapshot files to the configured output. It is possible |
| | 95 | to use a custom, unregistered output at record time using the same |
| | 96 | options supported by the `add-output` action. |
| | 97 | |
| | 98 | NOTE: Before taking a snapshot on a system with a high event throughput, |
| | 99 | it is recommended to first run `lttng stop` (see |
| | 100 | man:lttng-stop(1)). Otherwise, the snapshot could contain "holes", |
| | 101 | the result of the tracers overwriting unconsumed trace packets during |
| | 102 | the record operation. After the snapshot is recorded, the tracers can be |
| | 103 | started again with `lttng start` (see man:lttng-start(1)). |
| | 104 | |
| | 105 | |
| | 106 | include::common-cmd-options-head.txt[] |
| | 107 | |
| | 108 | |
| | 109 | Target |
| | 110 | ~~~~~~ |
| | 111 | option:-s 'SESSION', option:--session='SESSION':: |
| | 112 | Take a snapshot of the sub-buffers of the channels contained in |
| | 113 | the tracing session named 'SESSION' instead of the current |
| | 114 | tracing session. |
| | 115 | |
| | 116 | |
| | 117 | Snapshot output |
| | 118 | ~~~~~~~~~~~~~~~ |
| | 119 | option:-C 'URL', option:--ctrl-url='URL':: |
| | 120 | Set control path URL to 'URL' (must use option:--data-url option |
| | 121 | also). |
| | 122 | |
| | 123 | option:-D 'URL', option:--data-url='URL':: |
| | 124 | Set data path URL to 'URL' (must use option:--ctrl-url option |
| | 125 | also). |
| | 126 | |
| | 127 | option:-m 'SIZE', option:--max-size='SIZE':: |
| | 128 | Limit the total size of all the snapshot files written when |
| | 129 | recording a snapshot to 'SIZE' bytes. The `k` (kiB), `M` (MiB), |
| | 130 | and `G` (GiB) suffixes are supported. |
| | 131 | |
| | 132 | option:-n 'NAME', option:--name='NAME':: |
| | 133 | Assign the name 'NAME' to the snapshot output. |
| | 134 | |
| | 135 | |
| | 136 | include::common-cmd-help-options.txt[] |
| | 137 | |
| | 138 | |
| | 139 | include::common-cmd-footer.txt[] |
| | 140 | |
| | 141 | |
| | 142 | SEE ALSO |
| | 143 | -------- |
| | 144 | man:lttng(1) |
projects / lttng-tools.git / blame_incremental