X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng.1;h=14c081e63fa072953877dd1c7e7ef0f4c412a433;hp=99941db93af0d0a5d4436c91bbe230c7d67e70ac;hb=ee2758e57eeeb732ac513bca02fe8a6979d0d8b1;hpb=3ae6f6665030769040c46549ce4b4c9117ee09f6 diff --git a/doc/man/lttng.1 b/doc/man/lttng.1 index 99941db93..14c081e63 100644 --- a/doc/man/lttng.1 +++ b/doc/man/lttng.1 @@ -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,7 +96,10 @@ 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. @@ -107,30 +110,34 @@ 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 @@ -152,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 @@ -172,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. @@ -183,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 @@ -219,62 +235,83 @@ $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: -.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-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. -\-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