-.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] <COMMAND>
-.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 or JUL 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 or \-j). 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
.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).
.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"
Simple listing of lttng commands.
.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
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
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
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;
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
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.
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
$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 paremeter 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
-\-h, \-\-help
- Show summary of possible options and commands.
-\-\-list-options
- Simple listing of options
-\-o, \-\-output PATH
- Specify output path for traces
+$ lttng-relayd -o /tmp/lttng
+$ lttng create --live 200000 -U net://localhost
+$ lttng enable-event -a --userspace
+$ lttng start
.fi
-.IP
+After the start, you'll be able to read the events while they are being
+recorded in /tmp/lttng.
+
+.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
+# lttng create -U net://192.168.1.42
+.fi
+Uses TCP and default ports for the given destination.
+
+.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
+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: 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)
+$ 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
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
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 "\-\-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.
+.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:
+
+.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.
-.IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
.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
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
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)
+.RE
+.PP
-.IP "\fBlist\fP [\-k|\-u] [SESSION [SESSION_OPTIONS]]"
-.nf
+.PP
+\fBlist\fP [OPTIONS] [SESSION [SESSION OPTIONS]]
+.RS
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 \-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 \-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 "\-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 and the system session configuration directory will be
+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.
+.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/ or /var/run/lttng/sessions/ for root user). The default
+session configuration file naming scheme is \fBSESSION.lttng\fP.
+
+.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 <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.
+
+.TP
+\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.
+
+.TP
+\fBlist-output\fP [-s <NAME>]
+
+List the output of a session. Attributes of the output are printed.
+
+.TP
+\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.
+
.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 maxium size does not include the
+metadata file. Human readable format is accepted: {+k,+M,+G}. For instance,
+\-\-max-size 5M
+
+The minimum size of a snapshot is computed by multiplying the total amount of
+streams in the session by the largest subbuffer size. This is to ensure
+fairness between channels when extracting data.
+.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 DOMAIN"
+This section explains the JUL domain (\-j, \-\-jul) where JUL stands for Java
+Util Logging. You can use that feature by using the \fBliblttng-ust-jul.so\fP
+from the lttng-ust(3) project.
-.B OPTIONS:
+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 with the JUL domain, you enable a Logger name that will then be
+mapped to a default UST tracepoint called \fBlttng_jul:jul_event\fP in the
+\fBlttng_jul_channel\fP. Using the lttng-ctl API, any JUL events must use the
+tracepoint event type (same as \-\-tracepoint).
+
+Because of the default immutable channel (\fBlttng_jul_channel\fP), the
+\fBenable-channel\fP command CAN NOT be used with the JUL domain thus not
+having any \-j option.
+
+For JUL event, loglevels are supported with the JUL ABI values. 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 JUL registered
+applications to the session daemon by using \fBlttng list \-j\fP.
+
+Here is an example on how to use this 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 "<lttng/lttng-error.h>"
+for a detailed list or use lttng_strerror() to get a human readable string of
+the error code.
+.PP
+
.SH "ENVIRONMENT VARIABLES"
.PP
.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
.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 <lttng-dev@lists.lttng.org> to help improve this project.
+mailing list <lttng-dev@lists.lttng.org> to help improve this project or
+at https://bugs.lttng.org which is a bugtracker.
+.PP
+
.SH "CREDITS"
.PP
.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.
projects / lttng-tools.git / blobdiff