doc/man/lttng.1.txt

   1 lttng(1)
   2 ========
   3 :revdate: 16 October 2019
   4
   5
   6 NAME
   7 ----
   8 lttng - LTTng 2 tracer control command-line tool
   9
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 *lttng* [option:--group='GROUP'] [option:--mi=xml] [option:--no-sessiond | option:--sessiond-path='PATH']
  15       [option:--quiet | option:-verbose...] '<<commands,COMMAND>>' ['COMMAND OPTIONS']
  16
  17
  18 DESCRIPTION
  19 -----------
  20 include::common-intro.txt[]
  21
  22 The `lttng` command-line tool, as well as any user application linked
  23 with the LTTng control library (`liblttng-ctl`), sends commands to a
  24 listening LTTng session daemon (man:lttng-sessiond(8)). A session
  25 daemon:
  26
  27 * Manages tracing sessions (see man:lttng-create(1) to learn more
  28   about tracing sessions).
  29
  30 * Controls the various components (like tracers and consumer daemons) of
  31   LTTng.
  32
  33 * Sends asynchronous notifications to user applications.
  34
  35 By default, the man:lttng-create(1) command automatically spawns a
  36 session daemon for your Unix user if none is currently running. Override
  37 the path of the session daemon binary to spawn with the
  38 option:--sessiond-path option. Avoid automatically spawning a session
  39 daemon with the option:--no-sessiond option.
  40
  41 NOTE: The LTTng project recommends that you start the session daemon at
  42 boot time for stable and long-term tracing.
  43
  44
  45 Session daemon connection
  46 ~~~~~~~~~~~~~~~~~~~~~~~~~
  47 For most of its commands, the `lttng` tool needs to connect to a
  48 listening LTTng session daemon (man:lttng-sessiond(8)) to control LTTng
  49 tracing.
  50
  51 Each Unix user may have its own independent running session daemon.
  52 However, the `lttng` tool must connect to the session daemon of the
  53 `root` user (the root session daemon) to control Linux kernel tracing.
  54
  55 How the `lttng` tool chooses which session daemon to connect to
  56 is as follows:
  57
  58 If your Unix user is `root`::
  59     Connect to the root session daemon.
  60
  61 If your Unix user is not `root`::
  62     If your Unix user is part of the Unix tracing group:::
  63         Try to connect to the root session daemon.
  64 +
  65 If the root session daemon isn't running, connect to the session daemon
  66 of your Unix user.
  67
  68     If your Unix user is not part of the tracing group:::
  69         Connect to the session daemon of your Unix user.
  70
  71 The name of the Unix tracing group is one of:
  72
  73 With the nloption:--group='GROUP' option of the root session daemon (man:lttng-sessiond(8))::
  74     'GROUP'
  75 +
  76 In that case, you must use the option:--group='GROUP' option, with
  77 the same 'GROUP' argument, of the `lttng` tool.
  78
  79 Without the nloption:--group option of the root session daemon::
  80     `tracing`
  81
  82 LTTng-instrumented user applications automatically register to both the
  83 root session daemon and the user session daemon. This makes it possible
  84 for both session daemons to list the available traceable applications
  85 and known instrumentation points (see man:lttng-list(1)).
  86
  87
  88 OPTIONS
  89 -------
  90 option:-g 'GROUP', option:--group='GROUP'::
  91     Set the name of the Unix tracing group to 'GROUP' instead of
  92     `tracing`.
  93 +
  94 You must use this option to be able to connect to a root session daemon
  95 (man:lttng-sessiond(8)) which was started with its own
  96 nloption:--group='GROUP' option.
  97
  98 option:-m `xml`, option:--mi=++xml++::
  99     Print the command's result using a stable XML machine interface (MI)
 100     output instead of the default, unstable human-readable output.
 101 +
 102 With this mode, `lttng` prints the resulting XML document to the
 103 standard output, while it prints any error/warning to the standard error
 104 with an unstable, human-readable format.
 105 +
 106 If any error occurs during the execution of `lttng`, the command
 107 exits with a status different than{nbsp}0, and `lttng` does
 108 :not: guarantee the syntax and data validity of its MI output.
 109 +
 110 An XML schema definition (XSD) file used for validation of the MI output
 111 is available: see the `src/common/mi_lttng.xsd` file in the LTTng-tools
 112 source tree.
 113
 114 option:-n, option:--no-sessiond::
 115     Do not automatically spawn a session daemon for your Unix user when
 116     running the man:lttng-create(1) command.
 117 +
 118 You may :not: use this option with the option:--sessiond-path option.
 119
 120 option:-q, option:--quiet::
 121     Suppress all messages, including warnings and errors.
 122 +
 123 You may :not: use this option with the option:--verbose option.
 124
 125 option:--sessiond-path='PATH'::
 126     Set the absolute path of the session daemon binary to spawn from the
 127     man:lttng-create(1) command to 'PATH'.
 128 +
 129 You may :not: use this option with the option:--no-sessiond option.
 130
 131 option:-v, option:--verbose::
 132     Increase verbosity.
 133 +
 134 Specify this option up to three times to get more levels of verbosity.
 135 +
 136 You may :not: use this option with the option:--quiet option.
 137
 138
 139 Program information
 140 ~~~~~~~~~~~~~~~~~~~
 141 include::common-help-option.txt[]
 142
 143 option:--list-commands::
 144     List available commands and quit.
 145
 146 option:-V, option:--version::
 147     Show version and quit.
 148
 149
 150 [[commands]]
 151 COMMANDS
 152 --------
 153 The following commands also have their own nloption:--help option.
 154
 155
 156 Tracing session
 157 ~~~~~~~~~~~~~~~
 158 [options="header"]
 159 |===
 160 |Command |Description
 161
 162 |man:lttng-create(1) |{cmd_descr_create}.
 163 |man:lttng-destroy(1) |{cmd_descr_destroy}.
 164 |man:lttng-disable-rotation(1) |{cmd_descr_disable_rotation}.
 165 |man:lttng-enable-rotation(1) |{cmd_descr_enable_rotation}.
 166 |man:lttng-load(1) |{cmd_descr_load}.
 167 |man:lttng-regenerate(1) |{cmd_descr_regenerate}.
 168 |man:lttng-rotate(1) |{cmd_descr_rotate}.
 169 |man:lttng-save(1) |{cmd_descr_save}.
 170 |man:lttng-set-session(1) |{cmd_descr_set_session}.
 171 |man:lttng-snapshot(1) |{cmd_descr_snapshot}.
 172 |man:lttng-start(1) |{cmd_descr_start}.
 173 |man:lttng-status(1) |{cmd_descr_status}.
 174 |man:lttng-stop(1) |{cmd_descr_stop}.
 175 |===
 176
 177
 178 Channel
 179 ~~~~~~~
 180 [options="header"]
 181 |===
 182 |Command |Description
 183
 184 |man:lttng-add-context(1) |{cmd_descr_add_context}.
 185 |man:lttng-disable-channel(1) |{cmd_descr_disable_channel}.
 186 |man:lttng-enable-channel(1) |{cmd_descr_enable_channel}.
 187 |===
 188
 189
 190 Recording event rule
 191 ~~~~~~~~~~~~~~~~~~~~
 192 [options="header"]
 193 |===
 194 |Command |Description
 195
 196 |man:lttng-disable-event(1) |{cmd_descr_disable_event}.
 197 |man:lttng-enable-event(1) |{cmd_descr_enable_event}.
 198 |===
 199
 200 Information
 201 ~~~~~~~~~~~
 202 [options="header"]
 203 |===
 204 |Command |Description
 205
 206 |man:lttng-list(1) |{cmd_descr_list}.
 207 |===
 208
 209 Resource tracking
 210 ~~~~~~~~~~~~~~~~~
 211 [options="header"]
 212 |===
 213 |Command |Description
 214
 215 |man:lttng-track(1) |{cmd_descr_track}.
 216 |man:lttng-untrack(1) |{cmd_descr_untrack}.
 217 |===
 218
 219 Trigger
 220 ~~~~~~~
 221 [options="header"]
 222 |===
 223 |Command |Description
 224
 225 |man:lttng-add-trigger(1) |{cmd_descr_add_trigger}.
 226 |man:lttng-list-triggers(1) |{cmd_descr_list_triggers}.
 227 |man:lttng-remove-trigger(1) |{cmd_descr_remove_trigger}.
 228 |===
 229
 230 Miscellaneous
 231 ~~~~~~~~~~~~~
 232 [options="header"]
 233 |===
 234 |Command |Description
 235
 236 |man:lttng-help(1) |{cmd_descr_help}.
 237 |man:lttng-version(1) |{cmd_descr_version}.
 238 |man:lttng-view(1) |{cmd_descr_view}.
 239 |===
 240
 241
 242 include::common-cmd-footer.txt[]
 243
 244
 245 SEE ALSO
 246 --------
 247 man:babeltrace2(1),
 248 man:lttng-relayd(8),
 249 man:lttng-sessiond(8)