doc/man/lttng.1.txt

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