.TH "LTTNG" "1" "December 3rd, 2012" "" ""
.SH "NAME"
-lttng \(em LTTng 2.1.x tracer control command line tool
+lttng \(em LTTng 2.x tracer control command line tool
.SH "SYNOPSIS"
Please take a look at the help (\-h/\-\-help) for a detailed list of available
contexts.
-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 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.
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:
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:
.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:
\-\-overwrite
Flight recorder mode : overwrites events when subbuffers are full
\-\-subbuf-size SIZE
- Subbuffer size in bytes (default: 4096, kernel default: 262144)
+ 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: 4)
- Needs to be a power of 2 for kernel and ust tracers
+ 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 usec (default: 0)
- Needs to be a power of 2 for kernel and ust tracers
+ Switch subbuffer timer interval in µsec.
+ (default UST uid: 0, UST pid: 0, kernel: 0, metadata: 0)
\-\-read-timer USEC
- Read timer interval in usec (default: 200)
+ 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
-.fi
-
-.IP
+ (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 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
.IP "\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
.nf
\-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
\-\-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:
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]"
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
Simple listing of options
\-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
.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 <SIZE>] [-s <NAME>] [-n <NAME>] <URL> | -C <URL> -D <URL>
+
+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 <NAME>]
+
+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 <NAME>]
+
+List the output of a session. Attributes of the output are printed.
+
+\fBrecord\fP [-m <SIZE>] [-s <NAME>] [-n <NAME>] [<URL> | -C <URL> -D <URL>]
+
+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
projects / lttng-tools.git / blobdiff