-.TH "LTTNG" "1" "February 9, 2012" "" ""
+.TH "LTTNG" "1" "July 17, 2012" "" ""
.SH "NAME"
lttng \(em LTTng 2.0 tracer control command line tool
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 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
.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).
.IP
-.IP "\fBcreate\fP [OPTIONS] [NAME]
+.IP "\fBcreate\fP [NAME] [OPTIONS]
.nf
Create tracing session.
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.
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
.nf
\-h, \-\-help
Show summary of possible options and commands.
+\-a, \-\-all
+ Destroy all sessions
\-\-list-options
Simple listing of options
.fi
.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
\-\-subbuf-size
Subbuffer size in bytes (default: 4096, kernel default: 262144)
\-\-num-subbuf
- Number of subbufers (default: 4)
+ 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)
.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
+ 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 "\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
.nf
Enable tracing event
\-c, \-\-channel
Apply on channel name
\-a, \-\-all
- Enable all tracepoints
+ Enable all tracepoints and syscalls
\-k, \-\-kernel
Apply for the kernel tracer
\-u, \-\-userspace
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]"
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
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
\-\-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
.IP
-.IP "\fBstart\fP [OPTIONS] [NAME]"
+.IP "\fBstart\fP [NAME] [OPTIONS]"
.nf
Start tracing
.IP
-.IP "\fBstop\fP [OPTIONS] [NAME]"
+.IP "\fBstop\fP [NAME] [OPTIONS]"
.nf
Stop tracing
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:
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 <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
-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.
+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 <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.
.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.