X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng.1;h=e831867a2fe7c5b9fe51f9008684c6a3a631d824;hp=0de06d7cbec62ede56a73a24b40bf452ae486269;hb=5975c30aac46bd29da9331652180a8de3c9e2d6e;hpb=7972aab22f74b18faa168c0482216a3dd711a075 diff --git a/doc/man/lttng.1 b/doc/man/lttng.1 index 0de06d7cb..e831867a2 100644 --- a/doc/man/lttng.1 +++ b/doc/man/lttng.1 @@ -1,7 +1,7 @@ .TH "LTTNG" "1" "December 3rd, 2012" "" "" .SH "NAME" -lttng \(em LTTng 2.1.x tracer control command line tool +lttng \(em LTTng 2.x tracer control command line tool .SH "SYNOPSIS" @@ -82,9 +82,9 @@ Simple listing of lttng options. Simple listing of lttng commands. .SH "COMMANDS" -.TP -\fBadd-context\fP -.nf +.PP +\fBadd-context\fP [OPTIONS] +.RS Add context to event(s) and/or channel(s). A context is basically extra information appended to a channel. For instance, @@ -96,40 +96,48 @@ For example, this command will add the context information 'prio' and two perf counters (hardware branch misses and cache misses), to all events in the trace data output: -# lttng add-context \-k \-t prio \-t perf:branch-misses \-t perf:cache-misses +.nf +# lttng add-context \-k \-t prio \-t perf:branch-misses \\ + \-t perf:cache-misses +.fi Please take a look at the help (\-h/\-\-help) for a detailed list of available contexts. -If no channel is given (\-c), the context is added to all channels. Otherwise -the context will be added only to the given channel (\-c). +If no channel is given (\-c), the context is added to all channels that were +already enabled. If the session has no channel, a default channel is created. +Otherwise the context will be added only to the given channel (\-c). If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-s, \-\-session NAME - Apply on session name. -\-c, \-\-channel NAME - Apply on channel name. -\-k, \-\-kernel - Apply for the kernel tracer -\-u, \-\-userspace - Apply for the user-space tracer -\-t, \-\-type TYPE - Context type. You can repeat this option on the command line. Please - use "lttng add-context \-h" to list all available types. -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-s, \-\-session NAME" +Apply on session name. +.TP +.BR "\-c, \-\-channel NAME" +Apply on channel name. +.TP +.BR "\-k, \-\-kernel" +Apply for the kernel tracer +.TP +.BR "\-u, \-\-userspace" +Apply for the user-space tracer +.TP +.BR "\-t, \-\-type TYPE" +Context type. You can repeat this option on the command line. Please +use "lttng add-context \-h" to list all available types. +.RE +.PP -.IP "\fBcalibrate\fP" -.nf +.PP +\fBcalibrate\fP [OPTIONS] +.RS Quantify LTTng overhead The LTTng calibrate command can be used to find out the combined average @@ -151,16 +159,21 @@ an empty function, gathering PMU counters LLC (Last Level Cache) misses information (see lttng add-context \-\-help to see the list of available PMU counters). +.nf # lttng create calibrate-function -# lttng enable-event calibrate \-\-kernel \-\-function lttng_calibrate_kretprobe -# lttng add-context \-\-kernel \-t perf:LLC-load-misses \-t perf:LLC-store-misses \\ - \-t perf:LLC-prefetch-misses +# lttng enable-event calibrate \-\-kernel \\ + \-\-function lttng_calibrate_kretprobe +# lttng add-context \-\-kernel \-t perf:LLC-load-misses \\ + \-t perf:LLC-store-misses \\ + \-t perf:LLC-prefetch-misses # lttng start # for a in $(seq 1 10); do \\ lttng calibrate \-\-kernel \-\-function; done # lttng destroy -# babeltrace $(ls \-1drt ~/lttng-traces/calibrate-function-* | tail \-n 1) +# babeltrace $(ls \-1drt ~/lttng-traces/calibrate-function-* \\ + | tail \-n 1) +.fi The output from babeltrace can be saved to a text file and opened in a spreadsheet (e.g. oocalc) to focus on the per-PMU counter delta between @@ -171,10 +184,12 @@ staying on the same CPU must be considered. The average result, for the i7, on 10 samples: +.nf Average Std.Dev. perf_LLC_load_misses: 5.0 0.577 perf_LLC_store_misses: 1.6 0.516 perf_LLC_prefetch_misses: 9.0 14.742 +.fi As we can notice, the load and store misses are relatively stable across runs (their standard deviation is relatively low) compared to the prefetch misses. @@ -182,25 +197,27 @@ We can conclude from this information that LLC load and store misses can be accounted for quite precisely, but prefetches within a function seems to behave too erratically (not much causality link between the code executed and the CPU prefetch activity) to be accounted for. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-k, \-\-kernel - Apply for the kernel tracer -\-u, \-\-userspace - Apply for the user-space tracer -\-\-function - Dynamic function entry/return probe (default) -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-k, \-\-kernel" +Apply for the kernel tracer +.TP +.BR "\-u, \-\-userspace" +Apply for the user-space tracer +.TP +.BR "\-\-function" +Dynamic function entry/return probe (default) +.RE +.PP -.IP "\fBcreate\fP [NAME] [OPTIONS] -.nf +.PP +.IP \fBcreate\fP [NAME] [OPTIONS] +.RS Create tracing session. A tracing session contains channel(s) which contains event(s). It is domain @@ -214,142 +231,226 @@ automatically created having this form: 'auto-yyyymmdd-hhmmss'. If no \fB\-o, \-\-output\fP is specified, the traces will be written in $HOME/lttng-traces. -.fi + +The $HOME environment variable can be overridden by defining the environment +variable LTTNG_HOME. This is useful when the user running the commands has +a non-writeable home directory. .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-o, \-\-output PATH - Specify output path for traces +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-o, \-\-output PATH" +Specify output path for traces +.TP +.BR "\-\-no-output" +Traces will not be outputed +.TP +.BR "\-\-snapshot" +Set the session in snapshot mode. Created in no-output mode and uses the +URL, if one, as the default snapshot output. Every channel will be set +in overwrite mode and with mmap output (splice not supported). +.TP +.BR "\-U, \-\-set-url=URL" +Set URL for the consumer output destination. It is persistent for the +session lifetime. Redo the command to change it. This will set both data +and control URL for network. +.TP +.BR "\-C, \-\-ctrl-url=URL" +Set control path URL. (Must use -D also) +.TP +.BR "\-D, \-\-data-url=URL" +Set data path URL. (Must use -C also) +.PP Using these options, each API call can be controlled individually. For instance, \-C does not enable the consumer automatically. You'll need the \-e option for that. -\-U, \-\-set-uri=URL - Set URL for the consumer output destination. It is persistent for the - session lifetime. Redo the command to change it. This will set both - data and control URL for network. -\-C, \-\-ctrl-url=URL - Set control path URL. (Must use -D also) -\-D, \-\-data-url=URL - Set data path URL. (Must use -C also) - .B URL FORMAT: proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH] Supported protocols are (proto): -> file://... - Local filesystem full path. +.TP +.BR "file://..." +Local filesystem full path. -> net://... - This will use the default network transport layer which is TCP for both - control (PORT1) and data port (PORT2). The default ports are - respectively 5342 and 5343. Note that net[6]:// is not yet supported. +.TP +.BR "net://..." +This will use the default network transport layer which is TCP for both +control (PORT1) and data port (PORT2). The default ports are +respectively 5342 and 5343. Note that net[6]:// is not yet supported. -> tcp[6]://... - Can only be used with -C and -D together +.TP +.BR "tcp[6]://..." +Can only be used with -C and -D together NOTE: IPv6 address MUST be enclosed in brackets '[]' (rfc2732) .B EXAMPLES: +.nf # lttng create -U net://192.168.1.42 +.fi Uses TCP and default ports for the given destination. +.nf # lttng create -U net6://[fe80::f66d:4ff:fe53:d220] +.fi Uses TCP, default ports and IPv6. +.nf # lttng create s1 -U net://myhost.com:3229 -Create session s1 and set its consumer to myhost.com on port 3229 for control. .fi +Create session s1 and set its consumer to myhost.com on port 3229 for control. +.RE +.PP -.IP - -.IP "\fBdestroy\fP [OPTIONS] [NAME]" -.nf +.PP +\fBdestroy\fP [NAME] [OPTIONS] +.RS Teardown tracing session Free memory on the session daemon and tracer side. It's gone! If NAME is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-a, \-\-all - Destroy all sessions -\-\-list-options - Simple listing of options -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-a, \-\-all" +Destroy all sessions +.TP +.BR "\-\-list-options" +Simple listing of options +.RE +.PP -.IP "\fBenable-channel\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]" -.nf +.PP +\fBenable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS] +.RS Enable tracing channel -To enable event, you must first enable a channel which contains event(s). +To enable an event, you must enable both the event and the channel that +contains it. If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. +Exactly one of \-k or -u must be specified. + It is important to note that if a certain type of buffers is used, the session -will be set with that type and all other subsequent channel need to have the +will be set with that type and all other subsequent channel needs to have the same type. -.fi + +Note that once the session has been started and enabled on the tracer side, +it's not possible anymore to enable a new channel for that session. .B OPTIONS: +.TP +.BR "\-h, \-\-help" +Show this help +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-s, \-\-session NAME" +Apply on session name +.TP +.BR "\-k, \-\-kernel" +Apply to the kernel tracer +.TP +.BR "\-u, \-\-userspace" +Apply to the user-space tracer +.TP +.BR "\-\-discard" +Discard event when subbuffers are full (default) +.TP +.BR "\-\-overwrite" +Flight recorder mode : overwrites events when subbuffers are full +.TP +.BR "\-\-subbuf-size SIZE" +Subbuffer size in bytes {+k,+M,+G}. +(default UST uid: 131072, UST pid: 4096, kernel: 262144, metadata: 4096) +Rounded up to the next power of 2. + +The minimum subbuffer size, for each tracer, is the max value between +the default above and the system page size. You can issue this command +to get the current page size on your system: \fB$ getconf PAGE_SIZE\fP +.TP +.BR "\-\-num-subbuf NUM" +Number of subbuffers. (default UST uid: 4, UST pid: 4, kernel: 4, +metadata: 2) Rounded up to the next power of 2. +.TP +.BR "\-\-switch-timer USEC" +Switch subbuffer timer interval in µsec. +(default UST uid: 0, UST pid: 0, kernel: 0, metadata: 0) +.TP +.BR "\-\-read-timer USEC" +Read timer interval in µsec. +(default UST uid: 0, UST pid: 0, kernel: 200000, metadata: 0) +.TP +.BR "\-\-output TYPE" +Channel output type. Possible values: mmap, splice +(default UST uid: mmap, UST pid: mmap, kernel: splice, metadata: mmap) +.TP +.BR "\-\-buffers-uid" +Use per UID buffer (\-u only). Buffers are shared between applications +that have the same UID. +.TP +.BR "\-\-buffers-pid" +Use per PID buffer (\-u only). Each application has its own buffers. +.TP +.BR "\-\-buffers-global" +Use shared buffer for the whole system (\-k only) +.TP +.BR "\-C, \-\-tracefile-size SIZE" +Maximum size of each tracefile within a stream (in bytes). +0 means unlimited. (default: 0) +.TP +.BR "\-W, \-\-tracefile-count COUNT" +Used in conjunction with \-C option, this will limit the number of files +created to the specified count. 0 means unlimited. (default: 0) + +.B EXAMPLES: + .nf -\-h, \-\-help - Show this help -\-\-list-options - Simple listing of options -\-s, \-\-session NAME - Apply on session name -\-k, \-\-kernel - Apply to the kernel tracer -\-u, \-\-userspace - Apply to the user-space tracer - -\-\-discard - Discard event when subbuffers are full (default) -\-\-overwrite - Flight recorder mode : overwrites events when subbuffers are full -\-\-subbuf-size SIZE - Subbuffer size in bytes (default: 4096, kernel default: 262144) -\-\-num-subbuf NUM - Number of subbuffers (default: 4) - Needs to be a power of 2 for kernel and ust tracers -\-\-switch-timer USEC - Switch subbuffer timer interval in usec (default: 0) - Needs to be a power of 2 for kernel and ust tracers -\-\-read-timer USEC - Read timer interval in usec (default: 200) -\-\-output TYPE - Channel output type. Possible values: mmap, splice -\-\-buffers-uid - Use per UID buffer (\-u only). Buffers are shared between applications - that have the same UID. -\-\-buffers-pid - Use per PID buffer (\-u only). Each application has its own buffers. -\-\-buffers-global - Use shared buffer for the whole system (\-k only) +$ lttng enable-channel -k -C 4096 -W 32 chan1 .fi +For each stream, the maximum size of each trace file will be 4096 bytes, and +there will be a maximum of 32 different files. The file count is appended after +the stream number as seen in the following example. The last trace file is +smaller than 4096 since it was not completely filled. -.IP +.nf + ~/lttng-traces/[...]/chan1_0_0 (4096) + ~/lttng-traces/[...]/chan1_0_1 (4096) + ~/lttng-traces/[...]/chan1_0_2 (3245) + ~/lttng-traces/[...]/chan1_1_0 (4096) + ... +.fi -.IP "\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]" .nf +$ lttng enable-channel -k -C 4096 +.fi +This will create trace files of 4096 bytes and will create new ones as long as +there is data available. +.RE +.PP + +.PP +\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS] +.RS Enable tracing event A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is @@ -359,75 +460,104 @@ using the wildcard "*". If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-s, \-\-session NAME" +Apply on session name +.TP +.BR "\-c, \-\-channel NAME" +Apply on channel name +.TP +.BR "\-a, \-\-all" +Enable all tracepoints and syscalls. This actually enable a single +wildcard event "*". +.TP +.BR "\-k, \-\-kernel" +Apply for the kernel tracer +.TP +.BR "\-u, \-\-userspace" +Apply for the user-space tracer +.TP +.BR "\-\-tracepoint" +Tracepoint event (default). Userspace tracer supports wildcards at end +of string. Don't forget to quote to deal with bash expansion. +e.g.: .nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-s, \-\-session NAME - Apply on session name -\-c, \-\-channel NAME - Apply on channel name -\-a, \-\-all - Enable all tracepoints and syscalls. This actually enable a single - wildcard event "*". -\-k, \-\-kernel - Apply for the kernel tracer -\-u, \-\-userspace - Apply for the user-space tracer - -\-\-tracepoint - Tracepoint event (default) - - userspace tracer supports wildcards at end of string. Don't forget to - quote to deal with bash expansion. - e.g.: "*" "app_component:na*" -\-\-loglevel NAME - Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h). -\-\-loglevel-only NAME - Tracepoint loglevel (only this loglevel). - - The loglevel or loglevel-only options should be combined with a - tracepoint name or tracepoint wildcard. -\-\-probe [addr | symbol | symbol+offset] - Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...) - or hexadecimal (0xNNN...) -\-\-function [addr | symbol | symbol+offset] - Dynamic function entry/return probe. Addr and offset can be octal - (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...) -\-\-syscall - System call event. Enabling syscalls tracing (kernel tracer), you will - not be able to disable them with disable-event. This is a known - limitation. You can disable the entire channel to do the trick. - -\-\-filter 'expression' - Set a filter on a newly enabled event. Filter expression on event - fields, event recording depends on evaluation. Only specify on first - activation of a given event within a session. Filter only allowed when - enabling events within a session before tracing is started. If the - filter fails to link with the event within the traced domain, the event - will be discarded. Currently, filter is only implemented for the - user-space tracer. - - Expression examples: - - 'intfield > 500 && intfield < 503' - '(stringfield == "test" || intfield != 10) && intfield > 33' - 'doublefield > 1.1 && intfield < 5.3' - - Wildcards are allowed at the end of strings: - 'seqfield1 == "te*"' - In string literals, the escape character is a '\\'. Use '\\*' for - the '*' character, and '\\\\' for the '\\' character. .fi +.TP +.BR "\-\-loglevel NAME" +Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h). +.TP +.BR "\-\-loglevel-only NAME" +Tracepoint loglevel (only this loglevel). +The loglevel or loglevel-only options should be combined with a +tracepoint name or tracepoint wildcard. +.TP +.BR "\-\-probe (addr | symbol | symbol+offset)" +Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...) +or hexadecimal (0xNNN...) +.TP +.BR "\-\-function (addr | symbol | symbol+offset)" +Dynamic function entry/return probe. Addr and offset can be octal +(0NNN...), decimal (NNN...) or hexadecimal (0xNNN...) +.TP +.BR "\-\-syscall" +System call event. Enabling syscalls tracing (kernel tracer), you will +not be able to disable them with disable-event. This is a known +limitation. You can disable the entire channel to do the trick. +.TP +.BR "\-\-filter 'expression'" +Set a filter on a newly enabled event. Filter expression on event +fields and context. Event recording depends on evaluation. Only +specify on first activation of a given event within a session. +Filter only allowed when enabling events within a session before +tracing is started. If the filter fails to link with the event +within the traced domain, the event will be discarded. +Currently, filter is only implemented for the user-space tracer. + +Expression examples: -.IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]" .nf + 'intfield > 500 && intfield < 503' + '(strfield == "test" || intfield != 10) && intfield > 33' + 'doublefield > 1.1 && intfield < 5.3' +.fi + +Wildcards are allowed at the end of strings: + 'seqfield1 == "te*"' +In string literals, the escape character is a '\\'. Use '\\*' for +the '*' character, and '\\\\' for the '\\' character. Wildcard +match any sequence of characters, including an empty sub-string +(match 0 or more characters). + +Context information can be used for filtering. The examples below show +usage of context filtering on process name (with a wildcard), process ID +range, and unique thread ID for filtering. The process and thread ID of +running applications can be found under columns "PID" and "LWP" of the +"ps -eLf" command. + +.nf + '$ctx.procname == "demo*"' + '$ctx.vpid >= 4433 && $ctx.vpid < 4455' + '$ctx.vtid == 1234' +.fi + +.RE +.PP + +.PP +\fBdisable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS] +.RS Disable tracing channel Disabling a channel makes all event(s) in that channel to stop tracing. You can @@ -435,25 +565,30 @@ enable it back by calling \fBlttng enable-channel NAME\fP again. If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-s, \-\-session NAME - Apply on session name -\-k, \-\-kernel - Apply for the kernel tracer -\-u, \-\-userspace - Apply for the user-space tracer -.fi +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-s, \-\-session NAME" +Apply on session name +.TP +.BR "\-k, \-\-kernel" +Apply for the kernel tracer +.TP +.BR "\-u, \-\-userspace" +Apply for the user-space tracer +.RE +.PP -.IP "\fBdisable-event\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]" -.nf +.PP +\fBdisable-event\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS] +.RS Disable tracing event The event, once disabled, can be re-enabled by calling \fBlttng enable-event @@ -461,28 +596,34 @@ NAME\fP again. If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-s, \-\-session NAME - Apply on session name -\-a, \-\-all-events - Disable all events. This does NOT disable "*" but rather - every known events of the session. -\-k, \-\-kernel - Apply for the kernel tracer -\-u, \-\-userspace - Apply for the user-space tracer -.fi +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-s, \-\-session NAME" +Apply on session name +.TP +.BR "\-a, \-\-all-events" +Disable all events. This does NOT disable "*" but rather every known +events of the session. +.TP +.BR "\-k, \-\-kernel" +Apply for the kernel tracer +.TP +.BR "\-u, \-\-userspace" +Apply for the user-space tracer +.RE +.PP -.IP "\fBlist\fP [\-k|\-u] [SESSION [SESSION_OPTIONS]]" -.nf +.PP +\fBlist\fP [OPTIONS] [SESSION [SESSION OPTIONS]] +.RS List tracing session information. With no arguments, it will list available tracing session(s). @@ -496,74 +637,156 @@ calls events). With \-u alone, it will list all available user-space events from registered applications. Here is an example of 'lttng list \-u': +.nf PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello ust_tests_hello:tptest_sighandler (type: tracepoint) ust_tests_hello:tptest (type: tracepoint) +.fi You can now enable any event listed by using the name : \fBust_tests_hello:tptest\fP. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-k, \-\-kernel - Select kernel domain -\-u, \-\-userspace - Select user-space domain. +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-k, \-\-kernel" +Select kernel domain +.TP +.BR "\-u, \-\-userspace" +Select user-space domain. +.PP .B SESSION OPTIONS: -\-c, \-\-channel NAME - List details of a channel -\-d, \-\-domain - List available domain(s) -.fi +.TP +.BR "\-c, \-\-channel NAME" +List details of a channel +.TP +.BR "\-d, \-\-domain" +List available domain(s) +.RE +.PP -.IP "\fBset-session\fP NAME" -.nf +.PP +\fBset-session\fP NAME [OPTIONS] +.RS Set current session name Will change the session name in the .lttngrc file. -.fi .B OPTIONS: +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.RE +.PP + +.PP +\fBsnapshot\fP [OPTIONS] ACTION +.RS +Snapshot command for LTTng session. + +.B OPTIONS: + +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options + +.PP +.B ACTION: + +.TP +\fBadd-output\fP [-m ] [-s ] [-n ] | -C -D + +Setup and add an snapshot output for a session. Output are the destination +where the snapshot will be sent. Only one output is permitted. To change it, +you'll need to delete it and add back the new one. + +.TP +\fBdel-output\fP ID | NAME [-s ] + +Delete an output for a session using the ID. You can either specify the +output's ID that can be found with list-output or the name. + +.TP +\fBlist-output\fP [-s ] + +List the output of a session. Attributes of the output are printed. + +.TP +\fBrecord\fP [-m ] [-s ] [-n ] [ | -C -D ] + +Snapshot a session's buffer(s) for all domains. If an URL is specified, it is +used instead of a previously added output. Specifying only a name or/and a max +size will override the current output values. For instance, you can record a +snapshot with a custom maximum size or with a different name. + .nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options +$ lttng add-output -n mysnapshot file:///data/snapshot +[...] +$ lttng snapshot record -n new_name_snapshot .fi -.IP +The above will create a snapshot in /data/snapshot/new_name_snapshot* directory +rather then in mysnapshot*/ -.IP "\fBstart\fP [NAME] [OPTIONS]" -.nf +.PP +.B DETAILED ACTION OPTIONS + +.TP +.BR "\-s, \-\-session NAME" +Apply to session name. +.TP +.BR "\-n, \-\-name NAME" +Name of the snapshot's output. +.TP +.BR "\-m, \-\-max-size SIZE" +Maximum size in bytes of the snapshot. The maxium size does not include +the metadata file. +.TP +.BR "\-C, \-\-ctrl-url URL" +Set control path URL. (Must use -D also) +.TP +.BR "\-D, \-\-data-url URL" +Set data path URL. (Must use -C also) +.RE +.PP + +.PP +\fBstart\fP [NAME] [OPTIONS] +.RS Start tracing It will start tracing for all tracers for a specific tracing session. - If NAME is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.RE +.PP -.IP "\fBstop\fP [NAME] [OPTIONS]" -.nf +.PP +\fBstop\fP [NAME] [OPTIONS] +.RS Stop tracing It will stop tracing for all tracers for a specific tracing session. Before @@ -572,36 +795,35 @@ until the trace is readable for the session. Use \-\-no-wait to avoid this behavior. If NAME is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-\-no-wait - Don't wait for data availability. -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP "\-\-no-wait" +Don't wait for data availability. +.RE +.PP -.IP "\fBversion\fP" -.nf +.PP +\fBversion\fP +.RS Show version information -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.RE +.PP .IP "\fBview\fP [SESSION_NAME] [OPTIONS]" .nf