Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LTTNG(1)			 LTTng Manual			      LTTNG(1)

NAME
       lttng - LTTng 2 tracer control command-line tool

SYNOPSIS
       lttng [--group=GROUP] [--mi=TYPE] [--no-sessiond	| --sessiond-path=PATH]
	     [--quiet |	-v | -vv | -vvv] COMMAND [COMMAND OPTIONS]

DESCRIPTION
       The Linux Trace Toolkit:	next generation	<http://lttng.org/> is an open
       source software package used for	correlated tracing of the Linux
       kernel, user applications, and user libraries.

       LTTng consists of Linux kernel modules (for Linux kernel	tracing) and
       dynamically loaded libraries (for user application and library
       tracing).

       An LTTng	session	daemon,	lttng-sessiond(8), receives commands from the
       command-line interface lttng to control the LTTng tracers. All
       interactions with the LTTng tracers happen through the lttng tool or
       through the liblttng-ctl	library	shipped	with the LTTng-tools package.

       A tracing domain	is a tracer category. There are	five available
       domains.	For some commands, the domain needs to be specified with a
       command-line option. The	domain options are:

       -j, --jul
	   Apply command to the	java.util.logging (JUL)	domain.

       -k, --kernel
	   Apply command to the	Linux kernel domain.

       -l, --log4j
	   Apply command to the	Apache log4j 1.2
	   <https://logging.apache.org/log4j/1.2/> (Java) domain.

       -p, --python
	   Apply command to the	Python <https://www.python.org/> domain.

       -u, --userspace
	   Apply command to the	user space domain (application using
	   liblttng-ust	directly; see lttng-ust(3)).

       The LTTng session daemon	is a tracing registry which allows the user to
       interact	with multiple tracers (kernel and user space) within the same
       container, a tracing session. Traces can	be gathered from the Linux
       kernel and/or from instrumented applications (see lttng-ust(3)).	You
       can aggregate and read the events of LTTng traces using babeltrace(1).

       To trace	the Linux kernel, the session daemon needs to be running as
       root. LTTng uses	a tracing group	to allow specific users	to interact
       with the	root session daemon. The default tracing group name is
       tracing.	You can	use the	--group	option to set the tracing group	name
       to use.

       Session daemons can coexist. You	can have a session daemon running as
       user Alice that can be used to trace her	applications alongside a root
       session daemon or a session daemon running as user Bob.

	   Note
	   It is highly	recommended to start the session daemon	at boot	time
	   for stable and long-term tracing.

       User applications instrumented with LTTng automatically register	to the
       root session daemon and to user session daemons.	This allows any
       session daemon to list the available traceable applications and event
       sources (see lttng-list(1)).

       By default, the lttng-create(1) command automatically spawns a user
       session daemon if none is currently running. The	--no-sessiond general
       option can be set to avoid this.

OPTIONS
       -g GROUP, --group=GROUP
	   Use GROUP as	Unix tracing group (default: tracing).

       -m TYPE,	--mi=TYPE
	   Print the command's result using the	machine	interface type TYPE
	   instead of a	human-readable output.

	   Supported types: xml.

	   The machine interface (MI) mode converts the	traditional
	   pretty-printing to a	machine	output syntax. The MI mode provides a
	   change-resistant way	to access information generated	by the lttng
	   command-line	program.

	   When	using the MI mode, the data is printed to the standard output.
	   Errors and warnings are printed on the standard error with the
	   pretty-print	default	format.

	   If any error	occurs during the execution of a command, the return
	   value of the	command	will be	different than 0. In this case,	lttng
	   does	NOT guarantee the syntax and data validity of the generated MI
	   output.

	   For the xml MI type,	an XML schema definition (XSD) file used for
	   validation is available: see	the src/common/mi_lttng.xsd file in
	   the LTTng-tools source tree.

       -n, --no-sessiond
	   Do not automatically	spawn a	session	daemon.

       -q, --quiet
	   Suppress all	messages, including warnings and errors.

       --sessiond-path=PATH
	   Set the session daemon binary's absolute path to PATH.

       -v, --verbose
	   Increase verbosity.

	   Three levels	of verbosity are available, which are triggered	by
	   appending additional	v letters to the option	(that is, -vv and
	   -vvv).

   Program information
       -h, --help
	   Show	help.

       --list-commands
	   List	available commands.

       --list-options
	   List	available general options.

       -V, --version
	   Show	version.

COMMANDS
       The following commands also have	their own --help option.

   Tracing sessions
       lttng-create(1)
	   Create a tracing session.

       lttng-destroy(1)
	   Tear	down tracing sessions.

       lttng-load(1)
	   Load	tracing	session	configurations.

       lttng-regenerate(1)
	   Manage an LTTng tracing session's data regeneration.

       lttng-save(1)
	   Save	tracing	session	configurations.

       lttng-set-session(1)
	   Set current tracing session.

   Channels
       lttng-add-context(1)
	   Add context fields to a channel.

       lttng-disable-channel(1)
	   Disable tracing channels.

       lttng-enable-channel(1)
	   Create or enable tracing channels.

   Event rules
       lttng-disable-event(1)
	   Disable event rules.

       lttng-enable-event(1)
	   Create or enable event rules.

   Status
       lttng-list(1)
	   List	tracing	sessions, domains, channels, and events.

       lttng-status(1)
	   Get the status of the current tracing session.

   Control
       lttng-snapshot(1)
	   Snapshot buffers of current tracing session.

       lttng-start(1)
	   Start tracing.

       lttng-stop(1)
	   Stop	tracing.

   Resource tracking
       lttng-track(1)
	   Track specific system resources.

       lttng-untrack(1)
	   Untrack specific system resources.

   Miscellaneous
       lttng-help(1)
	   Display help	information about a command.

       lttng-version(1)
	   Show	version	information.

       lttng-view(1)
	   Start trace viewer.

ENVIRONMENT VARIABLES
       LTTNG_ABORT_ON_ERROR
	   Set to 1 to abort the process after the first error is encountered.

       LTTNG_HOME
	   Overrides the $HOME environment variable. Useful when the user
	   running the commands	has a non-writable home	directory.

       LTTNG_MAN_BIN_PATH
	   Absolute path to the	man pager to use for viewing help information
	   about LTTng commands	(using lttng-help(1) or	lttng COMMAND --help).

       LTTNG_SESSION_CONFIG_XSD_PATH
	   Path	in which the session.xsd session configuration XML schema may
	   be found.

       LTTNG_SESSIOND_PATH
	   Full	session	daemon binary path.

	   The --sessiond-path option has precedence over this environment
	   variable.

       Note that the lttng-create(1) command can spawn an LTTng	session	daemon
       automatically if	none is	running. See lttng-sessiond(8) for the
       environment variables influencing the execution of the session daemon.

FILES
       $LTTNG_HOME/.lttngrc
	   User	LTTng runtime configuration.

	   This	is where the per-user current tracing session is stored
	   between executions of lttng(1). The current tracing session can be
	   set with lttng-set-session(1). See lttng-create(1) for more
	   information about tracing sessions.

       $LTTNG_HOME/lttng-traces
	   Default output directory of LTTng traces. This can be overridden
	   with	the --output option of the lttng-create(1) command.

       $LTTNG_HOME/.lttng
	   User	LTTng runtime and configuration	directory.

       $LTTNG_HOME/.lttng/sessions
	   Default location of saved user tracing sessions (see	lttng-save(1)
	   and lttng-load(1)).

       /usr/local/etc/lttng/sessions
	   System-wide location	of saved tracing sessions (see lttng-save(1)
	   and lttng-load(1)).

	   Note
	   $LTTNG_HOME defaults	to $HOME when not explicitly set.

EXIT STATUS
       0
	   Success

       1
	   Command error

       2
	   Undefined command

       3
	   Fatal error

       4
	   Command warning (something went wrong during	the command)

BUGS
       If you encounter	any issue or usability problem,	please report it on
       the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.

RESOURCES
       o   LTTng project website <http://lttng.org>

       o   LTTng documentation <http://lttng.org/docs>

       o   Git repositories <http://git.lttng.org>

       o   GitHub organization <http://github.com/lttng>

       o   Continuous integration <http://ci.lttng.org/>

       o   Mailing list	<http://lists.lttng.org> for support and development:
	   lttng-dev@lists.lttng.org

       o   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net

COPYRIGHTS
       This program is part of the LTTng-tools project.

       LTTng-tools is distributed under	the GNU	General	Public License version
       2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
       LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
       for details.

THANKS
       Special thanks to Michel	Dagenais and the DORSAL	laboratory
       <http://www.dorsal.polymtl.ca/> at Ecole	Polytechnique de Montreal for
       the LTTng journey.

       Also thanks to the Ericsson teams working on tracing which helped us
       greatly with detailed bug reports and unusual test cases.

AUTHORS
       LTTng-tools was originally written by Mathieu Desnoyers,	Julien
       Desfossez, and David Goulet. More people	have since contributed to it.

       LTTng-tools is currently	maintained by Jeremie Galarneau
       <mailto:jeremie.galarneau@efficios.com>.

SEE ALSO
       lttng-sessiond(8), lttng-relayd(8), lttng-crash(1), lttng-ust(3),
       babeltrace(1)

LTTng 2.9.3			  01/09/2017			      LTTNG(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | COMMANDS | ENVIRONMENT VARIABLES | FILES | EXIT STATUS | BUGS | RESOURCES | COPYRIGHTS | THANKS | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=lttng&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help