doc/man/lttng.1.txt

   1 lttng(1)
   2 ========
   3 :doctype: manpage
   4
   5
   6 NAME
   7 ----
   8 lttng - LTTng 2.x tracer control command line tool
   9
  10
  11 SYNOPSIS
  12 --------
  13 *lttng* ['general-options'] 'command' ['command-options']
  14
  15
  16 DESCRIPTION
  17 -----------
  18 The LTTng project aims at providing highly efficient tracing tools for Linux.
  19 Its tracers help track down performance issues and debug problems
  20 involving multiple concurrent processes and threads. Tracing across multiple
  21 systems is also possible.
  22
  23 The *lttng* command line tool from the lttng-tools package is used to control
  24 both kernel and user-space tracing. Every interaction with the tracer should
  25 be done by this tool or by the liblttng-ctl library provided by the lttng-tools
  26 package.
  27
  28 LTTng uses a session daemon (*lttng-sessiond*(8)), acting as a tracing registry,
  29 which allows you to interact with multiple tracers (kernel and user-space)
  30 inside the same container, a tracing session. Traces can be gathered from the
  31 kernel and/or instrumented applications (*lttng-ust*(3)). Aggregating and
  32 reading those traces is done using the *babeltrace*(1) text viewer.
  33
  34 We introduce the notion of _tracing domains_ which is essentially a type of
  35 tracer (kernel, user space, JUL, LOG4J or Python for now). In the future, we
  36 could see more tracer like for instance an hypervisor. For some commands,
  37 you'll need to specify on which domain the command operates (*-u*, *-k*, *-l*,
  38 *-j* or *-p*). For instance, the kernel domain must be specified when enabling a
  39 kernel event.
  40
  41 In order to trace the kernel, the session daemon needs to be running as root.
  42 LTTng provides the use of a _tracing group_ (default: *tracing*). Whomever is
  43 in that group can interact with the root session daemon and thus trace the
  44 kernel. Session daemons can co-exist, meaning that you can have a session daemon
  45 running as Alice that can be used to trace her applications along side with a
  46 root daemon or even a Bob daemon. We highly recommend starting the session
  47 daemon at boot time for stable and long term tracing.
  48
  49 Each user-space application instrumented with *lttng-ust*(3) will automatically
  50 register with the root session daemon and its user session daemon. This allows
  51 each daemon to list the available traceable applications and tracepoints at any
  52 given moment (See the *list* command).
  53
  54
  55 OPTIONS
  56 -------
  57 This program follows the usual GNU command line syntax with long options
  58 starting with two dashes. Below is a summary of the available options.
  59
  60 *-h, --help*::
  61     Show summary of possible options and commands.
  62
  63 *-V, --version*::
  64     Show version.
  65
  66 *-v, --verbose*::
  67     Increase verbosity.
  68 +
  69 Three levels of verbosity are available which are triggered by putting
  70 additional *v* to the option (*-vv* or *-vvv*).
  71
  72 *-q, --quiet*::
  73     Suppress all messages (even errors).
  74
  75 *-g, --group='GROUP'*::
  76     Set unix tracing group name. (default: *tracing*)
  77
  78 *-n, --no-sessiond*::
  79     Don't automatically spawn a session daemon.
  80
  81 *--sessiond-path='PATH'*::
  82     Set session daemon full binary path.
  83
  84 *--list-options*::
  85     Simple listing of lttng commands.
  86
  87 *-m, --mi='TYPE'*::
  88     Machine interface
  89 +
  90 'TYPE' supported: *xml*
  91 +
  92 Machine interface (MI) mode converts the traditional pretty printing to a
  93 machine output syntax. MI mode provides a format change-resistant way to
  94 access information generated via the lttng command line.
  95 +
  96 When using MI mode, the data is printed on the standard output. Error and
  97 warning are printed on the standard error with the pretty print default
  98 format.
  99 +
 100 If any errors occur during the execution of a command, the return value of the
 101 command will be different than zero. In this case, lttng does NOT guarantee the
 102 syntax and data validity of the generated MI output.
 103 +
 104 For XML output type, a schema definition (XSD) file used for validation can be
 105 found under *src/common/mi_lttng.xsd*.
 106
 107
 108 COMMANDS
 109 --------
 110
 111 *lttng-add-context*(1)::
 112     Add context to event and/or channel
 113
 114 *lttng-calibrate*(1)::
 115     Quantify LTTng overhead
 116
 117 *lttng-create*(1)::
 118     Create tracing session
 119
 120 *lttng-destroy*(1)::
 121     Tear down tracing session
 122
 123 *lttng-enable-channel*(1)::
 124     Enable tracing channel
 125
 126 *lttng-enable-event*(1)::
 127     Enable tracing event
 128
 129 *lttng-disable-channel*(1)::
 130     Disable tracing channel
 131
 132 *lttng-disable-event*(1)::
 133     Disable tracing event
 134
 135 *lttng-list*(1)::
 136     List possible tracing options
 137
 138 *lttng-set-session*(1)::
 139     Set current session name
 140
 141 *lttng-snapshot*(1)::
 142     Snapshot buffers of current session name
 143
 144 *lttng-start*(1)::
 145     Start tracing
 146
 147 *lttng-stop*(1)::
 148     Stop tracing
 149
 150 *lttng-version*(1)::
 151     Show version information
 152
 153 *lttng-view*(1)::
 154     Start trace viewer
 155
 156 *lttng-save*(1)::
 157     Save session configuration
 158
 159 *lttng-load*(1)::
 160     Load session configuration
 161
 162 *lttng-track*(1)::
 163     Track specific system resources
 164
 165 *lttng-untrack*(1)::
 166     Untrack specific system resources
 167
 168 Each command also has its own -h, --help option.
 169
 170
 171 EXIT STATUS
 172 -----------
 173 *0*::
 174     Success
 175
 176 *1*::
 177     Command error
 178
 179 *2*::
 180     Undefined command
 181
 182 *3*::
 183     Fatal error
 184
 185 *4*::
 186     Command warning (something went wrong during the command)
 187
 188 Any other value above 10, please refer to *<lttng/lttng-error.h>* for a
 189 detailed list or use *lttng_strerror*() to get a human readable string
 190 of the error code.
 191
 192
 193 ENVIRONMENT VARIABLES
 194 ---------------------
 195 Note that all command line options override environment variables.
 196
 197 *LTTNG_SESSIOND_PATH*::
 198     Allows one to specify the full session daemon binary path to lttng command
 199     line tool. You can also use *--sessiond-path** option having the
 200     same effect.
 201
 202 *LTTNG_SESSION_CONFIG_XSD_PATH*::
 203     Set the path in which the *session.xsd* session configuration schema may be
 204     found.
 205
 206
 207 BUGS
 208 ----
 209 If you encounter any issues or usability problem, please report it on our
 210 mailing list *lttng-dev@lists.lttng.org* to help improve this project or
 211 at *https://bugs.lttng.org* which is a bug tracker.
 212
 213
 214 RESOURCES
 215 ---------
 216 A Web site is available at *http://lttng.org* for more information on the LTTng
 217 project.
 218
 219 You can also find our git tree at *http://git.lttng.org*.
 220
 221 Mailing lists for support and development: *lttng-dev@lists.lttng.org*.
 222
 223 You can find us on IRC server *irc.oftc.net* (OFTC) in *#lttng*.
 224
 225
 226 COPYRIGHTS
 227 ----------
 228 lttng is distributed under the GNU General Public License version 2. See the
 229 file *COPYING* for details.
 230
 231
 232 THANKS
 233 ------
 234 Thanks to Yannick Brosseau without whom this project would never have been so
 235 lean and mean! Also thanks to the Ericsson teams working on tracing which
 236 helped us greatly with detailed bug reports and unusual test cases.
 237
 238 Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
 239 maintainer) and Jon Bernard for our Debian packages.
 240
 241 Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
 242 Montreal for the LTTng journey.
 243
 244
 245 AUTHORS
 246 -------
 247 lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
 248 David Goulet. More people have since contributed to it. It is currently
 249 maintained by Jérémie Galarneau *jeremie.galarneau@efficios.com*.
 250
 251
 252 SEE ALSO
 253 --------
 254 *babeltrace*(1), *lttng-ust*(3), *lttng-sessiond*(8), *lttng-relayd*(8),
 255 *lttng-crash*(1)