X-Git-Url: http://git.efficios.com/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng.1;h=65fa3d17f465e2a2fcd1dbfb4ef0da8fd1d1c477;hp=f13d5d341d608b8e6a3c77106bf5e9be9e5ff235;hb=70d0b120691e90d81de7b38af8b845e261b5b40c;hpb=5c827ce0dce140b121032837510f89cb70d1650d diff --git a/doc/man/lttng.1 b/doc/man/lttng.1 index f13d5d341..65fa3d17f 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" @@ -23,11 +23,18 @@ 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 @@ -65,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" @@ -80,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 @@ -94,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. @@ -111,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 @@ -195,7 +199,7 @@ prefetch activity) to be accounted for. .IP -.IP "\fBcreate\fP [OPTIONS] [NAME] +.IP "\fBcreate\fP [NAME] [OPTIONS] .nf Create tracing session. @@ -221,6 +225,48 @@ $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-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. + +> 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 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 @@ -239,6 +285,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 @@ -249,10 +297,15 @@ 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). +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. + +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 +same type. .fi .B OPTIONS: @@ -262,7 +315,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 @@ -273,16 +326,48 @@ file. 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 +\-\-subbuf-size SIZE + Subbuffer size in bytes {+k,+M,+G} (default: 4096, kernel default: 262144) + Needs to be a power of 2 for both tracers +\-\-num-subbuf NUM Number of subbuffers (default: 4) - Needs to be a power of 2 for kernel and ust tracers -\-\-switch-timer - Switch subbuffer timer interval in usec (default: 0) - Needs to be a power of 2 for kernel and ust tracers -\-\-read-timer - Read timer interval in usec (default: 200) + Needs to be a power of 2 for both tracers +\-\-switch-timer USEC + Switch subbuffer timer interval in µsec (default: 0) +\-\-read-timer USEC + Read timer interval in µsec (UST default: 0, kernel default: 200000) +\-\-output TYPE + Channel output type. Possible values: mmap, splice +\-\-buffers-uid + Use per UID buffer (\-u only). Buffers are shared between applications + that have the same UID. +\-\-buffers-pid + 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). +\-W, \-\-tracefile-count COUNT + Used in conjunction with \-C option, this will limit the number + of files created to the specified count. + +.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 +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 @@ -307,12 +392,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 and syscalls + Enable all tracepoints and syscalls. This actually enable a single + wildcard event "*". \-k, \-\-kernel Apply for the kernel tracer \-u, \-\-userspace @@ -325,8 +411,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...) @@ -334,10 +425,41 @@ 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 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: + + '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. 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]" @@ -358,7 +480,7 @@ 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 @@ -384,8 +506,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 @@ -427,7 +552,8 @@ You can now enable any event listed by using the name : \-u, \-\-userspace Select user-space domain. -Session options: +.B SESSION OPTIONS: + \-c, \-\-channel NAME List details of a channel \-d, \-\-domain @@ -452,7 +578,7 @@ Will change the session name in the .lttngrc file. .IP -.IP "\fBstart\fP [OPTIONS] [NAME]" +.IP "\fBstart\fP [NAME] [OPTIONS]" .nf Start tracing @@ -472,11 +598,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 @@ -488,6 +617,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 @@ -536,115 +667,15 @@ If SESSION_NAME is omitted, the session name is taken from the .lttngrc file. .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. -.IP "0" -Success - -.IP "1" -Command error - -.IP "2" -Undefined command - -.IP "3" -Fatal error - -.IP "4" -Command warning - -.IP "16" -No session found by the name given - -.IP "18" -Error in session creation - -.IP "21" -Error in application(s) listing - -.IP "28" -Session name already exists - -.IP "33" -Kernel tracer unavailable +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. -.IP "35" -Kernel event exists - -.IP "37" -Kernel channel exists - -.IP "38" -Kernel channel creation failed - -.IP "39" -Kernel channel not found - -.IP "40" -Kernel channel disable failed - -.IP "41" -Kernel channel enable failed - -.IP "42" -Kernel context failed - -.IP "43" -Kernel enable event failed - -.IP "44" -Kernel disable event failed - -.IP "53" -Kernel listing events failed - -.IP "60" -UST channel disable failed - -.IP "61" -UST channel enable failed - -.IP "62" -UST adding context failed - -.IP "63" -UST event enable failed - -.IP "64" -UST event disable failed - -.IP "66" -UST start failed - -.IP "67" -UST stop failed - -.IP "75" -UST event exists - -.IP "76" -UST event not found - -.IP "77" -UST context exists - -.IP "78" -UST invalid context - -.IP "79" -Tracing the kernel requires a root lttng-sessiond daemon and "tracing" group -user membership. - -.IP "80" -Tracing already started - -.IP "81" -Tracing already stopped - -.IP "98" -No UST consumer detected - -.IP "99" -No Kernel consumer detected .PP .SH "ENVIRONMENT VARIABLES" @@ -657,17 +688,16 @@ Note that all command line options override environment variables. 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 are known yet in this 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