doc/man: lttng(1): update and standardize content
[lttng-tools.git] / doc / man / lttng.1.txt
CommitLineData
307a8468
PP
1lttng(1)
2========
307a8468
PP
3
4
5NAME
6----
5d231d82 7lttng - LTTng 2 tracer control command-line tool
307a8468
PP
8
9
10SYNOPSIS
11--------
5d231d82
PP
12[verse]
13*lttng* [option:--group='GROUP'] [option:--mi='TYPE'] [option:--no-sessiond | option:--sessiond-path='PATH']
14 [option:--quiet | option:-v | option:-vv | option:-vvv] 'COMMAND' ['COMMAND OPTIONS']
307a8468
PP
15
16
17DESCRIPTION
18-----------
5d231d82
PP
19The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
20source software package used for correlated tracing of the Linux kernel,
21user applications, and user libraries.
307a8468 22
5d231d82
PP
23LTTng consists of Linux kernel modules (for Linux kernel tracing) and
24dynamically loaded libraries (for user application and library tracing).
307a8468 25
5d231d82
PP
26An LTTng _session daemon_, linklttng:lttng-sessiond(8), receives
27commands from the command-line interface `lttng` to control the LTTng
28tracers. All interactions with the LTTng tracers happen through the
29`lttng` tool or through the liblttng-ctl library shipped with the
30LTTng-tools package.
307a8468 31
5d231d82
PP
32A _tracing domain_ is a tracer category. There are five available
33domains. For some commands, the domain needs to be specified with a
34command-line option. The domain options are:
307a8468 35
5d231d82
PP
36option:-j, option:--jul::
37 Apply command to the `java.util.logging` (JUL) domain.
307a8468 38
5d231d82
PP
39option:-k, option:--kernel::
40 Apply command to the Linux kernel domain.
307a8468 41
5d231d82
PP
42option:-l, option:--log4j::
43 Apply command to the Apache log4j 1.2 (Java) domain.
307a8468 44
5d231d82
PP
45option:-p, option:--python::
46 Apply command to the Python domain.
307a8468 47
5d231d82
PP
48option:-u, option:--userspace::
49 Apply command to the user space domain.
307a8468 50
5d231d82
PP
51The LTTng session daemon is a tracing registry which allows the user to
52interact with multiple tracers (kernel and user space) within the same
53container, a _tracing session_. Traces can be gathered from the Linux
54kernel and/or from instrumented applications (see
55linklttng:lttng-ust(3)). You can aggregate and read the events of LTTng
56traces using linklttng:babeltrace(1).
307a8468 57
5d231d82
PP
58To trace the Linux kernel, the session daemon needs to be running as
59`root`. LTTng uses a _tracing group_ to allow specific users to interact
60with the root session daemon. The default tracing group name is
61`tracing`. You can use the option:--group option to set the tracing
62group name to use.
307a8468 63
5d231d82
PP
64Session daemons can coexist. You can have a session daemon running as
65user Alice that can be used to trace her applications alongside a root
66session daemon or a session daemon running as user Bob.
307a8468 67
5d231d82
PP
68NOTE: It is highly recommended to start the session daemon at boot time
69for stable and long-term tracing.
307a8468 70
5d231d82
PP
71User applications instrumented with LTTng automatically register to the
72root session daemon and to user session daemons. This allows any session
73daemon to list the available traceable applications and event sources
74(see linklttng:lttng-list(1)).
307a8468 75
5d231d82
PP
76By default, the linklttng:lttng-create(1) command automatically spawns a
77user session daemon if none is currently running. The
78option:--no-sessiond general option can be set to avoid this.
307a8468 79
307a8468 80
5d231d82
PP
81OPTIONS
82-------
83option:-g, option:--group='GROUP'::
84 Use 'GROUP' as Unix tracing group (default: `tracing`).
307a8468 85
5d231d82
PP
86option:-m, option:--mi='TYPE'::
87 Print the command's result using the machine interface type 'TYPE'
88 instead of a human-readable output.
89+
90Supported types: `xml`.
91+
92The machine interface (MI) mode converts the traditional pretty-printing
93to a machine output syntax. The MI mode provides a change-resistant way
94to access information generated by the `lttng` command-line program.
95+
96When using the MI mode, the data is printed to the standard output.
97Errors and warnings are printed on the standard error with the
98pretty-print default format.
99+
100If any error occurs during the execution of a command, the return value
101of the command will be different than 0. In this case, `lttng` does
102:not: guarantee the syntax and data validity of the generated MI output.
103+
104For the `xml` MI type, an XML schema definition (XSD) file used for
105validation is available: see the `src/common/mi_lttng.xsd` file in
106the LTTng-tools source tree.
307a8468 107
5d231d82
PP
108option:-n, option:--no-sessiond::
109 Do not automatically spawn a session daemon.
307a8468 110
5d231d82
PP
111option:-q, option:--quiet::
112 Suppress all messages, including warnings and errors.
307a8468 113
5d231d82
PP
114option:--sessiond-path='PATH'::
115 Set the session daemon binary's absolute path to 'PATH'.
307a8468 116
5d231d82
PP
117option:-v, option:--verbose::
118 Increase verbosity.
119+
120Three levels of verbosity are available, which are triggered by
121appending additional `v` letters to the option
122(that is, `-vv` and `-vvv`).
307a8468 123
307a8468 124
5d231d82
PP
125Program information
126~~~~~~~~~~~~~~~~~~~
127option:-h, option:--help::
128 Show help.
307a8468 129
5d231d82
PP
130option:--list-commands::
131 List available commands.
307a8468 132
5d231d82
PP
133option:--list-options::
134 List available general options.
307a8468 135
5d231d82
PP
136option:-V, option:--version::
137 Show version.
307a8468 138
307a8468 139
5d231d82
PP
140COMMANDS
141--------
142The following commands also have their own option:--help option.
307a8468 143
307a8468 144
5d231d82
PP
145Tracing sessions
146~~~~~~~~~~~~~~~~
147linklttng:lttng-create(1)::
148 Create a tracing session.
307a8468 149
5d231d82
PP
150linklttng:lttng-destroy(1)::
151 Tear down tracing sessions.
307a8468 152
5d231d82
PP
153linklttng:lttng-save(1)::
154 Save tracing session configurations.
307a8468 155
5d231d82
PP
156linklttng:lttng-set-session(1)::
157 Set current tracing session.
307a8468 158
5d231d82
PP
159linklttng:lttng-load(1)::
160 Load tracing session configurations.
307a8468 161
307a8468 162
5d231d82
PP
163Channels
164~~~~~~~~
165linklttng:lttng-enable-channel(1)::
166 Create or enable tracing channels.
307a8468 167
5d231d82
PP
168linklttng:lttng-disable-channel(1)::
169 Disable tracing channels.
307a8468 170
5d231d82
PP
171linklttng:lttng-add-context(1)::
172 Add context fields to a channel.
307a8468 173
307a8468 174
5d231d82
PP
175Event rules
176~~~~~~~~~~~
177linklttng:lttng-enable-event(1)::
178 Create or enable event rules.
307a8468 179
5d231d82
PP
180linklttng:lttng-disable-event(1)::
181 Disable event rules.
307a8468 182
307a8468 183
5d231d82
PP
184Status
185~~~~~~
186linklttng:lttng-list(1)::
187 List tracing sessions, domains, channels, and events.
307a8468 188
5d231d82
PP
189linklttng:lttng-status(1)::
190 Get the status of the current tracing session.
307a8468 191
307a8468 192
5d231d82
PP
193Control
194~~~~~~~
195linklttng:lttng-snapshot(1)::
196 Snapshot buffers of current tracing session.
307a8468 197
5d231d82
PP
198linklttng:lttng-start(1)::
199 Start tracing.
307a8468 200
5d231d82
PP
201linklttng:lttng-stop(1)::
202 Stop tracing.
307a8468 203
307a8468 204
5d231d82
PP
205Resource tracking
206~~~~~~~~~~~~~~~~~
207linklttng:lttng-track(1)::
208 Track specific system resources.
307a8468 209
5d231d82
PP
210linklttng:lttng-untrack(1)::
211 Untrack specific system resources.
307a8468 212
307a8468 213
5d231d82
PP
214Miscellaneous
215~~~~~~~~~~~~~
216linklttng:lttng-calibrate(1)::
217 Quantify LTTng overhead.
307a8468 218
5d231d82
PP
219linklttng:lttng-help(1)::
220 Display help information about a command.
307a8468 221
5d231d82
PP
222linklttng:lttng-version(1)::
223 Show version information.
307a8468 224
5d231d82
PP
225linklttng:lttng-view(1)::
226 Start trace viewer.
307a8468
PP
227
228
5d231d82 229include::common-cmd-footer.txt[]
307a8468
PP
230
231
232SEE ALSO
233--------
5d231d82
PP
234linklttng:lttng-sessiond(8),
235linklttng:lttng-relayd(8),
236linklttng:lttng-crash(1),
237linklttng:lttng-ust(3),
238linklttng:babeltrace(1)
This page took 0.050175 seconds and 4 git commands to generate.