X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng.1;h=f773e61f89b7659ad95a5f2a8d9645d3c1ff0864;hp=2445b05ac1f9106e2f4089f94441001513a26560;hb=c56509420616421ef4f6fff53e1cf09f3ccd56b7;hpb=93e6c8a01b8c4a499b66eeeba2558cca2260de5f diff --git a/doc/man/lttng.1 b/doc/man/lttng.1 index 2445b05ac..f773e61f8 100644 --- a/doc/man/lttng.1 +++ b/doc/man/lttng.1 @@ -1,7 +1,7 @@ -.TH "LTTNG" "1" "February 9, 2012" "" "" +.TH "LTTNG" "1" "December 3rd, 2012" "" "" .SH "NAME" -lttng \(em LTTng 2.0 tracer control command line tool +lttng \(em LTTng 2.1.x tracer control command line tool .SH "SYNOPSIS" @@ -17,23 +17,30 @@ It's tracers help tracking down performance issues and debugging 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 +The \fBlttng\fP command line tool from the 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 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 or user space for now). In the future, we could see a third +tracer being for instance an hypervisor. For some commands, you'll need to +specify on which domain the command applies (-u or -k). For instance, enabling +a kernel event, you must specify the kernel domain to the command so we know +for which tracer this event is for. + 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 +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 to start the session daemon at boot time for stable and long term tracing. Every user-space applications instrumented with lttng-ust(3), will @@ -53,7 +60,8 @@ Show summary of possible options and commands. .TP .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" Suppress all messages (even errors). @@ -64,7 +72,7 @@ Set unix tracing group name. (default: tracing) .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" @@ -79,10 +87,10 @@ Simple listing of lttng commands. .nf 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 @@ -93,9 +101,8 @@ data output: 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. +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 \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. @@ -110,8 +117,6 @@ file. 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 @@ -194,7 +199,7 @@ prefetch activity) to be accounted for. .IP -.IP "\fBcreate\fP [OPTIONS] [NAME] +.IP "\fBcreate\fP [NAME] [OPTIONS] .nf Create tracing session. @@ -205,7 +210,7 @@ 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 $HOME/lttng-traces. @@ -220,6 +225,36 @@ $HOME/lttng-traces. Simple listing of options \-o, \-\-output PATH Specify output path for traces + +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 enable-consumer 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) + \-\-no-consumer + Don't activate a consumer for this session. + \-\-disable-consumer + Disable consumer for this session. + +See \fBenable-consumer\fP command below for the supported URL format. + +.B EXAMPLES: + +# lttng create -U net://192.168.1.42 +Uses TCP and default ports for the given destination. + +# lttng create -U net6://[fe80::f66d:4ff:fe53:d220] +Uses TCP, default ports and IPv6. + +# lttng create s1 -U net://myhost.com:3229 +Create session s1 and set its consumer to myhost.com on port 3229 for control. .fi .IP @@ -238,6 +273,8 @@ If NAME is omitted, the session name is taken from the .lttngrc file. .nf \-h, \-\-help Show summary of possible options and commands. +\-a, \-\-all + Destroy all sessions \-\-list-options Simple listing of options .fi @@ -248,6 +285,8 @@ If NAME is omitted, the session name is taken from the .lttngrc file. .nf Enable tracing channel +To enable event, you must first enable a channel which contains event(s). + If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. .fi @@ -259,7 +298,7 @@ file. Show this help \-\-list-options Simple listing of options -\-s, \-\-session +\-s, \-\-session NAME Apply on session name \-k, \-\-kernel Apply to the kernel tracer @@ -270,20 +309,96 @@ file. Discard event when subbuffers are full (default) \-\-overwrite Flight recorder mode : overwrites events when subbuffers are full -\-\-subbuf-size +\-\-subbuf-size SIZE Subbuffer size in bytes (default: 4096, kernel default: 262144) -\-\-num-subbuf - Number of subbufers (default: 8, kernel default: 4) +\-\-num-subbuf NUM + Number of subbuffers (default: 4) Needs to be a power of 2 for kernel and ust tracers -\-\-switch-timer +\-\-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 +\-\-read-timer USEC Read timer interval in usec (default: 200) +\-\-output TYPE + Channel output type. Possible values: mmap, splice .fi .IP +.IP "\fBenable-consumer\fP [-u|-k] [URL] [OPTIONS]" +.nf +Enable a consumer for the tracing session and domain. + +By default, every tracing session has a consumer attached to it using the local +filesystem as output. The trace is written in $HOME/lttng-traces. This command +allows the user to specify a specific URL after the session was created for a +specific domain. If no domain is specified, the consumer is applied on all +domains. + +Without options, the behavior is to enable a consumer to the current URL. The +default URL is the local filesystem at the path of the session mentioned above. + +The enable-consumer feature supports both local and network transport. You must +have a running \fBlttng-relayd(8)\fP for network transmission or any other daemon +that can understand the streaming protocol of LTTng. +.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 + +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 enable-consumer 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) +\-e, \-\-enable + Enable consumer + +.B URL FORMAT: + +proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH] + +Supported protocols are (proto): +> 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. + +> tcp[6]://... + Can only be used with -C and -D together + +NOTE: IPv6 address MUST be enclosed in brackets '[]' (rfc2732) + +.B EXAMPLES: + +$ lttng enable-consumer -u net://192.168.1.42 + +Uses TCP and default ports for user space tracing (-u) where the IP address +above is the destination machine where the traces will be streamed and a +\fBlttng-relayd(8)\fP is listening. +.fi + .IP "\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]" .nf Enable tracing event @@ -304,12 +419,13 @@ file. Show summary of possible options and commands. \-\-list-options Simple listing of options -\-s, \-\-session +\-s, \-\-session NAME Apply on session name -\-c, \-\-channel +\-c, \-\-channel NAME Apply on channel name \-a, \-\-all - Enable all tracepoints + Enable all tracepoints and syscalls. This actually enable a single + wildcard event "*". \-k, \-\-kernel Apply for the kernel tracer \-u, \-\-userspace @@ -322,8 +438,13 @@ file. e.g.: "*" "app_component:na*" -\-\-loglevel - Tracepoint loglevel +\-\-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...) @@ -331,10 +452,29 @@ file. 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. + 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 .IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]" @@ -355,7 +495,29 @@ file. Show summary of possible options and commands. \-\-list-options Simple listing of options -\-s, \-\-session +\-s, \-\-session NAME + Apply on session name +\-k, \-\-kernel + Apply for the kernel tracer +\-u, \-\-userspace + Apply for the user-space tracer +.fi + +.IP "\fBdisable-consumer\fP [\-k|\-u] [OPTIONS]" +.nf +Disable the consumer of a tracing session. + +This call MUST be done BEFORE tracing has started. +.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 @@ -381,8 +543,11 @@ file. Show summary of possible options and commands. \-\-list-options Simple listing of options -\-s, \-\-session +\-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 @@ -395,6 +560,10 @@ List tracing session information. With no arguments, it will list available tracing session(s). +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 @@ -416,11 +585,12 @@ You can now enable any event listed by using the name : \-\-list-options Simple listing of options \-k, \-\-kernel - Select kernel domain (FIXME : apparition de la notion de "domain" ici) + Select kernel domain \-u, \-\-userspace Select user-space domain. -Session options: +.B SESSION OPTIONS: + \-c, \-\-channel NAME List details of a channel \-d, \-\-domain @@ -445,7 +615,7 @@ Will change the session name in the .lttngrc file. .IP -.IP "\fBstart\fP [OPTIONS] [NAME]" +.IP "\fBstart\fP [NAME] [OPTIONS]" .nf Start tracing @@ -465,11 +635,14 @@ If NAME is omitted, the session name is taken from the .lttngrc file. .IP -.IP "\fBstop\fP [OPTIONS] [NAME]" +.IP "\fBstop\fP [NAME] [OPTIONS]" .nf 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 @@ -481,6 +654,8 @@ If NAME is omitted, the session name is taken from the .lttngrc file. Show summary of possible options and commands. \-\-list-options Simple listing of options +\-\-no-wait + Don't wait for data availability. .fi .IP @@ -507,8 +682,8 @@ View traces of a tracing session By default, the babeltrace viewer will be used for text viewing. -The SESSION_NAME is an optional session name. If not specified, lttng will get -it from the configuration file (.lttngrc). +If SESSION_NAME is omitted, the session name is taken from the .lttngrc file. + .fi .B OPTIONS: @@ -528,6 +703,17 @@ it from the configuration file (.lttngrc). to the arguments .fi +.SH "EXIT VALUES" +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 @@ -535,21 +721,20 @@ Note that all command line options override environment variables. .PP .PP -.IP "LTTNG_SESSIOND_PATH_ENV" +.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. .SH "SEE ALSO" - -.PP -babeltrace(1), lttng-ust(3), lttng-sessiond(8) -.PP +.BR babeltrace(1), +.BR lttng-ust(3), +.BR lttng-sessiond(8), +.BR lttng-relayd(8), +.BR lttng-health-check(3) .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 bugtracker. .SH "CREDITS" .PP @@ -570,7 +755,7 @@ 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.