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