X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng.1;h=f2b08bbfa9f6d665d499c0b364adde8b261e8c2f;hp=31fcbcc03986a1a898ebc85903786b2a60864b10;hb=6a9a8e6a5d37a9a7fc97d12a0fee7e4b254f1832;hpb=6991b1817066a4a0a618f85adfdfb9aa8f2bd524 diff --git a/doc/man/lttng.1 b/doc/man/lttng.1 index 31fcbcc03..f2b08bbfa 100644 --- a/doc/man/lttng.1 +++ b/doc/man/lttng.1 @@ -1,45 +1,50 @@ -.TH "LTTNG" "1" "February 9, 2012" "" "" +.TH "LTTNG" "1" "May 13th, 2014" "" "" .SH "NAME" -lttng \(em LTTng 2.0 tracer control command line tool +lttng \(em LTTng 2.x tracer control command line tool .SH "SYNOPSIS" .PP -.nf lttng [OPTIONS] -.fi .SH "DESCRIPTION" .PP The LTTng project aims at providing highly efficient tracing tools for Linux. -It's tracers help tracking down performance issues and debugging problems +Its tracers help track down performance issues and debug problems involving multiple concurrent processes and threads. Tracing across multiple systems is also possible. -The \fBlttng\fP command line tool from lttng-tools package is used to control -both kernel and user-space tracing. Every interactions with the tracer should -be done by this tool or by the liblttng-ctl provided with the lttng-tools +The \fBlttng\fP command line tool from the lttng-tools package is used to control +both kernel and user-space tracing. Every interaction with the tracer should +be done by this tool or by the liblttng-ctl library provided by the lttng-tools package. LTTng uses a session daemon (lttng-sessiond(8)), acting as a tracing registry, -which permits you to interact with multiple tracers (kernel and user-space) +which allows you to interact with multiple tracers (kernel and user-space) inside the same container, a tracing session. Traces can be gathered from the kernel and/or instrumented applications (lttng-ust(3)). Aggregating and reading those traces is done using the babeltrace(1) text viewer. +We introduce the notion of \fBtracing domains\fP which is essentially a type of +tracer (kernel, user space, JUL, LOG4J or Python for now). In the future, we +could see more tracer like for instance an hypervisor. For some commands, +you'll need to specify on which domain the command operates (\-u, \-k, \-l, \-j +or \-p). For instance, the kernel domain must be specified when enabling a +kernel event. + In order to trace the kernel, the session daemon needs to be running as root. LTTng provides the use of a \fBtracing group\fP (default: tracing). Whomever is in that group can interact with the root session daemon and thus trace the -kernel. Session daemons can co-exist meaning that you can have a session daemon -running as Alice that can be use to trace her applications along side with a -root daemon or even a Bob daemon. We highly recommand to start the session +kernel. Session daemons can co-exist, meaning that you can have a session daemon +running as Alice that can be used to trace her applications along side with a +root daemon or even a Bob daemon. We highly recommend starting the session daemon at boot time for stable and long term tracing. -Every user-space applications instrumented with lttng-ust(3), will -automatically register to the session daemon. This feature gives you the -ability to list available traceable applications and tracepoints on a per user -basis. (See \fBlist\fP command). +Each user-space application instrumented with lttng-ust(3) will automatically +register with the root session daemon and its user session daemon. This allows +each daemon to list the available traceable applications and tracepoints at any +given moment (See the \fBlist\fP command). .SH "OPTIONS" .PP @@ -48,83 +53,114 @@ two dashes. Below is a summary of the available options. .PP .TP -.BR "-h, --help" +.BR "\-h, \-\-help" Show summary of possible options and commands. .TP -.BR "-v, --verbose" +.BR "\-v, \-\-verbose" Increase verbosity. -FIXME : details (-v : sessiond verbose, -vv : consumerd verbose, etc) ? +Three levels of verbosity are available which are triggered by putting additional v to +the option (\-vv or \-vvv) .TP -.BR "-q, --quiet" +.BR "\-q, \-\-quiet" Suppress all messages (even errors). .TP -.BR "-g, --group NAME" +.BR "\-g, \-\-group NAME" Set unix tracing group name. (default: tracing) .TP -.BR "-n, --no-sessiond" +.BR "\-n, \-\-no-sessiond" Don't automatically spawn a session daemon. .TP -.BR "--sessiond-path" +.BR "\-\-sessiond\-path PATH" Set session daemon full binary path. .TP -.BR "--list-options" +.BR "\-\-list\-options" Simple listing of lttng options. .TP -.BR "--list-commands" +.BR "\-\-list\-commands" Simple listing of lttng commands. +.TP +.BR "\-m, \-\-mi TYPE +Machine interface + +TYPE supported: XML + +Machine interface (MI) mode converts the traditional pretty printing to a +machine output syntax. MI mode provides a format change-resistant way to access +information generated via the lttng command line. + +When using MI mode, the data is printed on \fBstdout\fP. Error and warning are +printed on \fBstderr\fP with the pretty print default format. + +If any errors occur during the execution of a command, the return value of the +command will be different than zero. In this case, lttng does NOT guarantee the +syntax and data validity of the generated MI output. + +For XML output type, a schema definition (XSD) file used for validation can be +found under src/common/mi_lttng.xsd + .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 or event. For -instance, you could ask the tracer to add the PID information within the -"sched_switch" kernel event. You can also add performance monitoring unit -counters (perf PMU) using the perf kernel API). +A context is basically extra information appended to a channel. For instance, +you could ask the tracer to add the PID information for all events in a +channel. You can also add performance monitoring unit counters (perf PMU) using +the perf kernel API. -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 +For example, this command will add the context information 'prio' and two per-CPU +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:cpu:branch-misses \\ + \-t perf:cpu:cache-misses +.fi -Please take a look at the help (-h/--help) for a detailed list of available +Please take a look at the help (\-h/\-\-help) for a detailed list of available contexts. -If no channel and no event is given (-c/-e), the context is added to all -channels (which applies automatically to all events in that channel). Otherwise -the context will be added only to the channel (-c) and/or event (-e) indicated. +Perf counters are available as per-CPU ("perf:cpu:...") and per-thread +("perf:thread:...") counters. Currently, per-CPU counters can only be +used with the kernel tracing domain, and per-thread counters can only be +used with the UST tracing domain. + +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 +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. --e, --event NAME - Apply on event 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 @@ -143,19 +179,24 @@ looking for "generic registers". This sequence of commands will gather a trace executing a kretprobe hooked on an empty function, gathering PMU counters LLC (Last Level Cache) misses -information (see lttng add-context --help to see the list of available PMU +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:cpu:LLC-load-misses \\ + \-t perf:cpu:LLC-store-misses \\ + \-t perf:cpu:LLC-prefetch-misses # lttng start # for a in $(seq 1 10); do \\ - lttng calibrate --kernel --function; + 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 @@ -166,10 +207,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. @@ -177,355 +220,876 @@ 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 [OPTIONS] [NAME] -.nf +.PP +\fBcreate\fP [NAME] [OPTIONS] +.RS Create tracing session. A tracing session contains channel(s) which contains event(s). It is domain -agnostic meaning that you can enable channels and events for either the +agnostic, meaning that channels and events can be enabled for the user-space tracer and/or the kernel tracer. It acts like a container aggregating multiple tracing sources. On creation, a \fB.lttngrc\fP file is created in your $HOME directory containing the current session name. If NAME is omitted, a session name is -automatically created having this form: 'auto-yyyymmdd-hhmms'. +automatically created having this form: 'auto-yyyymmdd-hhmmss'. -If no \fB-o, --output\fP is specified, the traces will be written in +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. + +The session name MUST NOT contain the character '/'. .B OPTIONS: +.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 output +.TP +.BR "\-\-snapshot" +Set the session in snapshot mode. Created in no-output mode and uses the +URL, if one is specified, as the default snapshot output. Every channel will be set +in overwrite mode and with mmap output (splice not supported). +.TP +.BR "\-\-live [USEC]" +Set the session exclusively in live mode. The parameter is the delay in micro +seconds before the data is flushed and streamed. The live mode allows you to +stream the trace and view it while it's being recorded by any tracer. For that, +you need a lttng-relayd and this session requires a network URL (\-U or +\-C/\-D). If no USEC nor URL is provided, the default is to use a timer value +set to 1000000 and the network URL set to net://127.0.0.1. + +To read a live session, you can use babeltrace(1) or the live streaming +protocol in doc/live-reading-protocol.txt. Here is an example: + +.nf +$ lttng-relayd -o /tmp/lttng +$ lttng create --live 200000 -U net://localhost +$ lttng enable-event -a --userspace +$ lttng start +.fi + +After the start, you'll be able to read the events while they are being +recorded in /tmp/lttng. + +.TP +.BR "\-\-shm-path PATH" + +Path where shared memory holding buffers should be created. Useful +when used with PRAMFS or other persistent memory filesystems to extract +trace data in the event of a crash requiring a reboot. + +.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. + +.B URL FORMAT: + +proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH] + +Supported protocols are (proto): +.TP +.BR "file://..." +Local filesystem full path. + +.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. + +.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 --h, --help - Show summary of possible options and commands. ---list-options - Simple listing of options --o, --output PATH - Specify output path for traces +# lttng create -U net://192.168.1.42 .fi +Uses TCP and default ports for the given destination. -.IP +.nf +# lttng create -U net6://[fe80::f66d:4ff:fe53:d220] +.fi +Uses TCP, default ports and IPv6. -.IP "\fBdestroy\fP [OPTIONS] [NAME]" .nf +# lttng create s1 -U net://myhost.com:3229 +.fi +Create session s1 and set its consumer to myhost.com on port 3229 for control. +.RE +.PP + +.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. ---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 -If \fB-s, --session\fP is omitted, the session name is taken from the .lttngrc +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. -.fi + +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 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. .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. The +number of subbuffer must be 2 or more. +.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) +Note: traces generated with this option may inaccurately report +discarded events as of CTF 1.8. +.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 - 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 - Subbuffer size in bytes (default: 4096, kernel default: 262144) ---num-subbuf - Number of subbufers (default: 8, kernel default: 4) ---switch-timer - Switch subbuffer timer interval in usec (default: 0) ---read-timer - Read timer interval in usec (default: 200) +$ 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 +A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is omitted, a default channel named '\fBchannel0\fP' is created and the event is -added to it. For the user-space tracer, using \fB-a, --all\fP is the same as -using the wildcard "*". +added to it. If \fB\-c, \-\-channel\fP is omitted, but a non-default +channel already exists within the session, an error is returned. For the +user-space tracer, using \fB\-a, \-\-all\fP is the same as using the +wildcard "*". -If \fB-s, --session\fP is omitted, the session name is taken from the .lttngrc +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 enables 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 "\-j, \-\-jul" +Apply for Java application using Java Util Logging interface (JUL) +.TP +.BR "\-l, \-\-log4j" +Apply for Java application using LOG4J +.TP +.BR "\-p, \-\-python" +Apply for Python application using the logging module. +.TP +.BR "\-\-tracepoint" +Tracepoint event (default). Userspace tracer supports wildcards at the 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 - Apply on session name --c, --channel - Apply on channel name --a, --all - Enable all tracepoints --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 - Tracepoint loglevel ---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. .fi +.TP +.BR "\-\-loglevel NAME" +Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h). +For the JUL domain, the loglevel ranges are detailed with the \-\-help +option thus starting from SEVERE to FINEST. +For the LOG4J domain, loglevels range from FATAL to TRACE which are also +detailed in the help. +For the Python domain, loglevels range from CRITICAL to DEBUG which are +detailed in the help as well. +.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. Also note +that per-syscall selection is not supported yet. Use with "-a" to enable +all syscalls. +.TP +.BR "\-\-filter 'expression'" +Set a filter on a newly enabled event. Filter expression on event +fields and context. The event will be recorded if the filter's +expression evaluates to TRUE. Only specify on first activation of a +given event within a session. +Specifying a filter is 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. +Filtering is currently 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 sequence. Wildcard +matches any sequence of characters, including an empty sub-string +(matches 0 or more characters). + +Context information can be used for filtering. The examples below shows +usage of context filtering on the process name (using a wildcard), process ID +range, and unique thread ID. The process and thread IDs 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 + +Context information is available to all filters whether or not the add-context +command has been used to add it to the event's channel, as long as the context +field exists for that domain. For example, the filter examples given above will +never fail to link: no add-context is required for the event's channel. + +.TP +.BR "\-x, \-\-exclude LIST" +Add exclusions to UST tracepoints: +Events that match any of the items in the comma-separated LIST are not +enabled, even if they match a wildcard definition of the event. + +This option is also applicable with the \fB\-a, \-\-all\fP option, +in which case all UST tracepoints are enabled except the ones whose +names match any of the items in LIST. +.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 -enable it back by calling \fBlttng enable-channel NAME\fP again. +Disabling a channel disables the tracing of all of the channel's events. A channel +can be re-enabled by calling \fBlttng enable-channel NAME\fP again. -If \fB-s, --session\fP is omitted, the session name is taken from the .lttngrc +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 - 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 NAME\fP again. -If \fB-s, --session\fP is omitted, the session name is taken from the .lttngrc +If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. -.fi + +If \fB\-c, \-\-channel\fP is omitted, the default channel name is used. +If \fB\-c, \-\-channel\fP is omitted, but a non-default channel already +exists within the session, an error is returned. .B OPTIONS: -.nf --h, --help - Show summary of possible options and commands. ---list-options - Simple listing of options --s, --session - 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 "\-c, \-\-channel NAME" +Apply on channel 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 +.TP +.BR "\-j, \-\-jul" +Apply for Java application using Java Util Logging interface (JUL) +.TP +.BR "\-l, \-\-log4j" +Apply for Java application using LOG4J +.TP +.BR "\-p, \-\-python" +Apply for Python application using the logging module. +.RE +.PP -.IP "\fBlist\fP [-k|-u] [SESSION [SESSION_OPTIONS]]" -.nf -List tracing session informations. +.PP +\fBlist\fP [OPTIONS] [SESSION [SESSION OPTIONS]] +.RS +List tracing session information. With no arguments, it will list available tracing session(s). -With -k alone, it will list all available kernel events (except the system +With the session name, it will display the details of the session including +the trace file path, the associated channels and their state (activated +and deactivated), the activated events and more. + +With \-k alone, it will list all available kernel events (except the system calls events). -With -u alone, it will list all available user-space events from registered -applications. Here is an example of 'lttng list -u': +With \-j alone, the available JUL event from registered application will be +list. The event corresponds to the Logger name in the Java JUL application. +With \-l alone, the available LOG4J event from registered application will be +list. The event corresponds to the Logger name in the Java LOG4J application. +With \-p alone, the available Python event from registered application will be +list. The event corresponds to the Logger name in the Python application. +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 (FIXME : apparition de la notion de "domain" ici) --u, --userspace - Select user-space domain. - -Session options: --c, --channel NAME - List details of a channel --d, --domain - List available domain(s) -.fi +.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. +.TP +.BR "\-j, \-\-jul" +Apply for Java application using JUL +.TP +.BR "\-l, \-\-log4j" +Apply for Java application using LOG4J +.TP +.BR "\-p, \-\-python" +Apply for Python application using the logging module. +.TP +.BR "\-f, \-\-fields" +List event fields -.IP "\fBset-session\fP NAME" -.nf +.PP +.B SESSION OPTIONS: + +.TP +.BR "\-c, \-\-channel NAME" +List details of a channel +.TP +.BR "\-d, \-\-domain" +List available domain(s) +.RE +.PP + +.PP +\fBload\fP [OPTIONS] [NAME] +.RS +Load tracing session configuration + +If NAME is omitted, all session configurations found in both the user's session +configuration directory (default: ~/.lttng/sessions/) and the system session +configuration directory (default: /etc/lttng/sessions/) will be loaded. Note +that the sessions in the user directory are loaded first and then the system +wide directory are loaded. + +.B OPTIONS: + +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-a, \-\-all" +Load all session configurations (default). +.TP +.BR "\-i, \-\-input-path PATH" +Specify the input path for session configurations. This overrides the default +session configuration directory. +.TP +.BR "\-f, -\-force" +Overwrite current session configuration(s) if a session of the same name +already exists. +.RE +.PP + +.PP +\fBsave\fP [OPTIONS] [SESSION] +.RS +Save tracing session configuration + +If SESSION is omitted, all session configurations will be saved to individual +\fB.lttng\fP files under the user's session configuration directory (default: +~/.lttng/sessions/). The default session configuration file naming scheme is +\fBSESSION.lttng\fP. + +For instance, a user in the tracing group saving a session from a root session +daemon will save it in her/his user directory. + +.B OPTIONS: + +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-a, \-\-all" +Save all session configurations (default). +.TP +.BR "\-o, \-\-output-path PATH" +Specify the output path for saved sessions. This overrides the default session +configuration directory. +.TP +.BR "\-f, -\-force" +Overwrite session configuration file if session name clashes. +.RE +.PP + +.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 a snapshot output for a session. Output is 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 output's ID. You can either specify the +output by name or use its ID as returned by the list-output command. + +.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 snapshot 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 [OPTIONS] [NAME]" -.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 maximum size does not include the +metadata file. Human readable format is accepted: {+k,+M,+G}. For instance, +\-\-max-size 5M +.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 [OPTIONS] [NAME]" -.nf +.PP +\fBstop\fP [NAME] [OPTIONS] +.RS Stop tracing -It will stop tracing for all tracers for a specific tracing session. +It will stop tracing for all tracers for a specific tracing session. Before +returning, the command checks for data availability meaning that it will wait +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 -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-\-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 +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.RE +.PP -.IP +.PP +\fBview\fP [SESSION_NAME] [OPTIONS] +.RS +View traces of a tracing session. By default, the babeltrace viewer +will be used for text viewing. If SESSION_NAME is omitted, the session +name is taken from the .lttngrc file. -.IP "\fBview\fP [SESSION_NAME] [OPTIONS]" -.nf -View traces of a tracing session +.B OPTIONS: -By default, the babeltrace viewer will be used for text viewing. +.TP +.BR "\-h, \-\-help" +Show this help +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-t, \-\-trace-path PATH" +Trace directory path for the viewer +.TP +.BR "\-e, \-\-viewer CMD" +Specify viewer and/or options to use This will completely override the +default viewers so please make sure to specify the full command. The +trace directory path of the session will be appended at the end to the +arguments +.RE +.PP -The SESSION_NAME is an optional session name. If not specified, lttng will get -it from the configuration file (.lttngrc). -.fi +.SH "JUL/LOG4J DOMAIN" -.B OPTIONS: +This section explains the JUL and LOG4J domain where JUL stands for Java Util +Logging. You can use these by using the \fBliblttng-ust--jni.so\fP from +the lttng-ust(3) project. + +The LTTng Java Agent uses JNI to link the UST tracer to the Java application +that uses the agent. Thus, it behaves similarly to the UST domain (\-u). When +enabling events, you enable a Logger name that will then be mapped to a default +UST tracepoint called \fBlttng_jul:_event\fP in the +\fBlttng__channel\fP. Using the lttng-ctl API, any JUL/LOG4J events +must use the tracepoint event type (same as \-\-tracepoint). + +Because of the default immutable channel, the \fBenable-channel\fP command CAN +NOT be used with the JUL and LOG4J domain thus not having any options. + +Also, loglevels are supported. Use \fBlttng enable-event \-h\fP to list them. +Wildcards are NOT supported except the "*" meaning all events (same as \-a). + +Exactly like the UST domain, if the Java application has the same UID as you, +you can trace it. Same goes for the tracing group accessing root applications. + +Finally, you can list every Logger name that are available from registered +applications to the session daemon by using \fBlttng list \-j\fP or \fB\-l\fP. + +Here is an example on how to use the JUL domain. .nf --h, --help - Show this help ---list-options - Simple listing of options --t, --trace-path PATH - Trace directory path for the viewer --e, --viewer CMD - Specify viewer and/or options to use - This will completely override the default viewers so - please make sure to specify the full command. The trace - directory path of the session will be appended at the end - to the arguments +$ lttng list -j +[...] +$ lttng create aSession +$ lttng enable-event -s aSession -j MyCustomLoggerName +$ lttng start .fi +More information can be found in the lttng-ust documentation, see +java-util-logging.txt +.PP + +.SH "EXIT VALUES" +.PP +On success 0 is returned and a positive value on error. Value of 1 means a command +error, 2 an undefined command, 3 a fatal error and 4 a command warning meaning that +something went wrong during the command. + +Any other value above 10, please refer to +.BR "" +for a detailed list or use lttng_strerror() to get a human readable string of +the error code. +.PP + .SH "ENVIRONMENT VARIABLES" .PP @@ -533,25 +1097,35 @@ Note that all command line options override environment variables. .PP .PP -.IP "LTTNG_SESSIOND_PATH_ENV" -Allows to specify the full session daemon binary path to lttng command line -tool. You can also use --sessiond-path option having the same effect. -.SH "SEE ALSO" +.IP "LTTNG_SESSIOND_PATH" +Allows one to specify the full session daemon binary path to lttng command line +tool. You can also use \-\-sessiond-path option having the same effect. +.PP .PP -babeltrace(1), lttng-ust(3), lttng-sessiond(8) +.IP "LTTNG_SESSION_CONFIG_XSD_PATH" +Set the path in which the \fBsession.xsd\fP session configuration schema may be +found. .PP + +.SH "SEE ALSO" +.BR babeltrace(1), +.BR lttng-ust(3), +.BR lttng-sessiond(8), +.BR lttng-relayd(8), + .SH "BUGS" .PP -No show stopper bugs known yet at this stable version. - If you encounter any issues or usability problem, please report it on our -mailing list to help improve this project. +mailing list to help improve this project or +at https://bugs.lttng.org which is a bug tracker. +.PP + .SH "CREDITS" .PP -lttng is distributed under the GNU public license version 2. See the file +lttng is distributed under the GNU General Public License version 2. See the file COPYING for details. .PP A Web site is available at http://lttng.org for more information on the LTTng @@ -568,18 +1142,18 @@ You can find us on IRC server irc.oftc.net (OFTC) in #lttng. .PP Thanks to Yannick Brosseau without whom this project would never have been so lean and mean! Also thanks to the Ericsson teams working on tracing which -helped us greatly with detailled bug reports and unusual test cases. +helped us greatly with detailed bug reports and unusual test cases. Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA maintainer) and Jon Bernard for our Debian packages. Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de Montreal for the LTTng journey. -.pp +.PP .SH "AUTHORS" .PP lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and David Goulet. More people have since contributed to it. It is currently -maintained by David Goulet . +maintained by Jérémie Galarneau . .PP