8 lttng - Control LTTng tracing
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']
21 include::common-intro.txt[]
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
28 * Manages recording sessions (see man:lttng-concepts(7) to learn more
29 about recording sessions).
31 * Controls the various components (like tracers and consumer daemons) of
34 * Sends asynchronous notifications to user applications.
36 By default, the man:lttng-create(1) command automatically spawns:
38 * A session daemon for your Unix user if none is currently running.
40 Override the path of the session daemon binary to spawn with the
41 option:--sessiond-path option.
43 Avoid automatically spawning a session daemon with the
44 option:--no-sessiond option.
46 * A relay daemon (see man:lttng-relayd(8)) if all the following
50 * You specify the nloption:--live option.
52 * You don't specify any of the nloption:--set-url, nloption:--ctrl-url,
53 or nloption:--data-url options.
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).
60 Override the path of the relay daemon binary to spawn with the
61 option:--relayd-path option.
63 NOTE: The LTTng project recommends that you start the session daemon at
64 boot time for stable and long-term tracing.
66 See man:lttng-concepts(7) to learn more about the foundational concepts
69 The `lttng` tool offers a subcommand-based command-line interface. The
70 ``<<commands,COMMANDS>>'' section below lists the available commands.
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
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.
83 How the `lttng` tool chooses which session daemon to connect to
86 If your Unix user is `root`::
87 Connect to the root session daemon.
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.
93 If the root session daemon isn't running, connect to the session daemon
96 If your Unix user is not part of the tracing group:::
97 Connect to the session daemon of your Unix user.
99 The name of the Unix tracing group is one of:
101 With the nloption:--group='GROUP' option of the root session daemon (man:lttng-sessiond(8))::
104 In that case, you must use the option:--group='GROUP' option, with
105 the same 'GROUP' argument, of the `lttng` tool.
107 Without the nloption:--group option of the root session daemon::
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)).
118 option:-g 'GROUP', option:--group='GROUP'::
119 Set the name of the Unix tracing group to 'GROUP' instead of
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.
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.
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.
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.
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
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.
146 You may :not: use this option with the option:--sessiond-path option.
148 option:-q, option:--quiet::
149 Suppress all messages, including warnings and errors.
151 You may :not: use this option with the option:--verbose option.
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'.
157 You may :not: use this option with the option:--no-sessiond option.
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'.
163 option:-v, option:--verbose::
166 Specify this option up to three times to get more levels of verbosity.
168 You may :not: use this option with the option:--quiet option.
173 include::common-help-option.txt[]
175 option:--list-commands::
176 List available commands and quit.
178 option:-V, option:--version::
179 Show version and quit.
185 The following commands also have their own nloption:--help option.
192 |Command |Description
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}.
214 |Command |Description
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}.
226 |Command |Description
228 |man:lttng-disable-event(1) |{cmd_descr_disable_event}.
229 |man:lttng-enable-event(1) |{cmd_descr_enable_event}.
236 |Command |Description
238 |man:lttng-list(1) |{cmd_descr_list}.
245 |Command |Description
247 |man:lttng-track(1) |{cmd_descr_track}.
248 |man:lttng-untrack(1) |{cmd_descr_untrack}.
255 |Command |Description
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}.
266 |Command |Description
268 |man:lttng-help(1) |{cmd_descr_help}.
269 |man:lttng-version(1) |{cmd_descr_version}.
270 |man:lttng-view(1) |{cmd_descr_view}.
274 include::common-lttng-cmd-after-options.txt[]
277 include::common-footer.txt[]
282 man:lttng-concepts(7)
284 man:lttng-sessiond(8)