X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng.1;h=21e9bb4630ea1b495e917769c1e7d82c77770e51;hp=5c94af4e15cb897fb37ef06af516f8918841f499;hb=5dfe3327652ef79bfea00bdf142422b3506ee413;hpb=50a3b92a9ee3779d8daa8292067290bea8889346 diff --git a/doc/man/lttng.1 b/doc/man/lttng.1 index 5c94af4e1..21e9bb463 100644 --- a/doc/man/lttng.1 +++ b/doc/man/lttng.1 @@ -1,7 +1,7 @@ -.TH "LTTNG" "1" "July 17, 2012" "" "" +.TH "LTTNG" "1" "December 3rd, 2012" "" "" .SH "NAME" -lttng \(em LTTng 2.0 tracer control command line tool +lttng \(em LTTng 2.x tracer control command line tool .SH "SYNOPSIS" @@ -72,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" @@ -87,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 @@ -101,9 +101,9 @@ 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 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. @@ -118,8 +118,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 @@ -217,6 +215,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: @@ -228,25 +230,44 @@ $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 option for that. -\-U, \-\-set-uri=URL - Set URL for the enable-consumer destination. It is persistent for the +\-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) - \-\-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 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: @@ -288,10 +309,18 @@ 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 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: @@ -301,7 +330,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 @@ -312,93 +341,60 @@ 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 - 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) -.fi - -.IP +\-\-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 +\-\-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. +\-\-switch-timer USEC + 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 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. +\-\-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). + 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) -.IP "\fBenable-consumer\fP [-u|-k] [URL] [OPTIONS]" -.nf -Enable a consumer for the tracing session and domain. +.B EXAMPLES: -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. +$ 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. -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. + ~/lttng-traces/[...]/chan1_0_0 (4096) + ~/lttng-traces/[...]/chan1_0_1 (4096) + ~/lttng-traces/[...]/chan1_0_2 (3245) + ~/lttng-traces/[...]/chan1_1_0 (4096) + ... -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. +$ 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 -.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 - -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[6]://... - 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. - -> 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 .IP "\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]" .nf @@ -420,12 +416,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 @@ -438,8 +435,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...) @@ -453,12 +455,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: @@ -469,7 +471,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]" @@ -498,28 +512,6 @@ file. 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 -\-u, \-\-userspace - Apply for the user-space tracer -.fi - .IP "\fBdisable-event\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]" .nf Disable tracing event @@ -538,8 +530,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 @@ -607,6 +602,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 @@ -631,7 +691,10 @@ If NAME is omitted, the session name is taken from the .lttngrc file. .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 @@ -643,6 +706,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 @@ -719,10 +784,6 @@ tool. You can also use \-\-sessiond-path option having the same effect. .BR lttng-health-check(3) .SH "BUGS" -With version 2.1 and earlier, if you start a tracing session and than enable -kernel events, they are not recorded and the tracing session fails to stop. To -fix this, simply enable events before starting the session. - If you encounter any issues or usability problem, please report it on our mailing list to help improve this project or at https://bugs.lttng.org which is a bugtracker.