X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng.1;h=3a358dd78ff21d919a8dd1d6760f5b2ca33866ca;hp=37c206398deeb1771813ca7592d8cafff7f27863;hb=2201988389cd5f7df8c41948302792e50d5bb52a;hpb=1cb514cec8d71a17376a1f2e78f0a68f2f410521 diff --git a/doc/man/lttng.1 b/doc/man/lttng.1 index 37c206398..3a358dd78 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 +.PP \fBadd-context\fP -.nf +.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,22 +197,23 @@ 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 @@ -214,6 +230,10 @@ 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. + +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. .fi .B OPTIONS: @@ -225,6 +245,13 @@ $HOME/lttng-traces. Simple listing of options \-o, \-\-output PATH Specify output path for traces +\-\-no-output + Traces will not be outputed +\-\-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). Using these options, each API call can be controlled individually. For instance, \-C does not enable the consumer automatically. You'll need the \-e @@ -304,8 +331,11 @@ If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngr file. 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. + +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. .fi .B OPTIONS: @@ -327,17 +357,25 @@ same type. \-\-overwrite Flight recorder mode : overwrites events when subbuffers are full \-\-subbuf-size SIZE - Subbuffer size in bytes {+k,+M,+G} (default: 4096, kernel default: 262144) + 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 \-\-num-subbuf NUM - Number of subbuffers (default: 4) + Number of subbuffers. (default UST uid: 4, UST pid: 4, kernel: 4, metadata: 2) Rounded up to the next power of 2. \-\-switch-timer USEC - Switch subbuffer timer interval in µsec (default: 0) + Switch subbuffer timer interval in µsec. + (default UST uid: 0, UST pid: 0, kernel: 0, metadata: 0) \-\-read-timer USEC - Read timer interval in µsec (UST default: 0, kernel default: 200000) + Read timer interval in µsec. + (default UST uid: 0, UST pid: 0, kernel: 200000, metadata: 0) \-\-output TYPE Channel output type. Possible values: mmap, splice + (default UST uid: mmap, UST pid: mmap, kernel: splice, metadata: mmap) \-\-buffers-uid Use per UID buffer (\-u only). Buffers are shared between applications that have the same UID. @@ -347,15 +385,16 @@ same type. Use shared buffer for the whole system (\-k only) \-C, \-\-tracefile-size SIZE Maximum size of each tracefile within a stream (in bytes). + 0 means unlimited. (default: 0) \-W, \-\-tracefile-count COUNT Used in conjunction with \-C option, this will limit the number - of files created to the specified count. + of files created to the specified count. 0 means unlimited. (default: 0) .B EXAMPLES: $ lttng enable-channel -C 4096 -W 32 chan1 -For each stream, the maximum size of a trace file will be 4096 bytes divided -over a \fBmaximum\fP of 32 different files. The file count is appended after +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. @@ -578,6 +617,71 @@ Will change the session name in the .lttngrc file. .IP +.IP "\fBsnapshot\fP ACTION" +.nf +Snapshot command for LTTng session. +.fi + +.B OPTIONS: + +.nf +\-h, \-\-help + Show summary of possible options and commands. +\-\-list-options + Simple listing of options +.fi + +.B ACTION: + +.nf +\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. + +\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. + +\fBlist-output\fP [-s ] + +List the output of a session. Attributes of the output are printed. + +\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. + +$ lttng add-output -n mysnapshot file:///data/snapshot +[...] +$ lttng snapshot record -n new_name_snapshot + +The above will create a snapshot in /data/snapshot/new_name_snapshot* directory +rather then in mysnapshot*/ +.fi + +.B LONG OPTIONS + +.nf +\-s, \-\-session NAME + Apply to session name. +\-n, \-\-name NAME + Name of the snapshot's output. +\-m, \-\-max-size SIZE + Maximum size in bytes of the snapshot. The maxium size does not + include the metadata file. +\-C, \-\-ctrl-url URL + Set control path URL. (Must use -D also) +\-D, \-\-data-url URL + Set data path URL. (Must use -C also) +.fi + +.IP + .IP "\fBstart\fP [NAME] [OPTIONS]" .nf Start tracing