X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng.1;h=3a358dd78ff21d919a8dd1d6760f5b2ca33866ca;hp=0a548f825e9ab925e0c8bc274e99624b2f6f6966;hb=2201988389cd5f7df8c41948302792e50d5bb52a;hpb=004f3466ecdda5e828d27d4a077a4234f57a2707 diff --git a/doc/man/lttng.1 b/doc/man/lttng.1 index 0a548f825..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 (default: 4096, kernel default: 262144) - Needs to be a power of 2 for both tracers + 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) - Needs to be a power of 2 for both tracers + 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 (default: 200) + 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. @@ -345,6 +383,30 @@ same type. Use per PID buffer (\-u only). Each application has its own buffers. \-\-buffers-global 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. 0 means unlimited. (default: 0) + +.B EXAMPLES: + +$ lttng enable-channel -C 4096 -W 32 chan1 +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. + + ~/lttng-traces/[...]/chan1_0_0 (4096) + ~/lttng-traces/[...]/chan1_0_1 (4096) + ~/lttng-traces/[...]/chan1_0_2 (3245) + ~/lttng-traces/[...]/chan1_1_0 (4096) + ... + +$ lttng enable-channel -C 4096 +This will create trace files of 4096 bytes and will create new ones as long as +there is data available. .fi .IP @@ -408,12 +470,12 @@ file. \-\-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. + 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: @@ -424,7 +486,19 @@ file. 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. + 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. + + '$ctx.procname == "demo*"' + '$ctx.vpid >= 4433 && $ctx.vpid < 4455' + '$ctx.vtid == 1234' .fi .IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]" @@ -543,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