doc/man/lttng.1.txt

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