doc/man: use specific revision date for each manual page
[lttng-tools.git] / doc / man / lttng.1.txt
... / ...
CommitLineData
1lttng(1)
2========
3:revdate: 16 October 2019
4
5
6NAME
7----
8lttng - LTTng 2 tracer control command-line tool
9
10
11SYNOPSIS
12--------
13[verse]
14*lttng* [option:--group='GROUP'] [option:--mi='TYPE'] [option:--no-sessiond | option:--sessiond-path='PATH']
15 [option:--quiet | option:-v | option:-vv | option:-vvv] '<<commands,COMMAND>>' ['COMMAND OPTIONS']
16
17
18DESCRIPTION
19-----------
20The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
21source software package used for correlated tracing of the Linux kernel,
22user applications, and user libraries.
23
24LTTng consists of Linux kernel modules (for Linux kernel tracing) and
25dynamically loaded libraries (for user application and library tracing).
26
27An LTTng _session daemon_, man:lttng-sessiond(8), receives
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.
32
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:
36
37nloption:-j, nloption:--jul::
38 Apply command to the `java.util.logging` (JUL) domain.
39
40nloption:-k, nloption:--kernel::
41 Apply command to the Linux kernel domain.
42
43nloption:-l, nloption:--log4j::
44 Apply command to the https://logging.apache.org/log4j/1.2/[Apache log4j 1.2]
45 (Java) domain.
46
47nloption:-p, nloption:--python::
48 Apply command to the https://www.python.org/[Python] domain.
49
50nloption:-u, nloption:--userspace::
51 Apply command to the user space domain (application using
52 liblttng-ust directly; see man:lttng-ust(3)).
53
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
58man:lttng-ust(3)). You can aggregate and read the events of LTTng
59traces using man:babeltrace(1).
60
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.
66
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.
70
71NOTE: It is highly recommended to start the session daemon at boot time
72for stable and long-term tracing.
73
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
77(see man:lttng-list(1)).
78
79By default, the man:lttng-create(1) command automatically spawns a
80user session daemon if none is currently running. The
81option:--no-sessiond general option can be set to avoid this.
82
83
84OPTIONS
85-------
86option:-g 'GROUP', option:--group='GROUP'::
87 Use 'GROUP' as Unix tracing group (default: `tracing`).
88
89option:-m 'TYPE', option:--mi='TYPE'::
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.
110
111option:-n, option:--no-sessiond::
112 Do not automatically spawn a session daemon.
113
114option:-q, option:--quiet::
115 Suppress all messages, including warnings and errors.
116
117option:--sessiond-path='PATH'::
118 Set the session daemon binary's absolute path to 'PATH'.
119
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`).
126
127
128Program information
129~~~~~~~~~~~~~~~~~~~
130option:-h, option:--help::
131 Show help.
132
133option:--list-commands::
134 List available commands.
135
136option:--list-options::
137 List available general options.
138
139option:-V, option:--version::
140 Show version.
141
142
143[[commands]]
144COMMANDS
145--------
146The following commands also have their own nloption:--help option.
147
148
149Tracing sessions
150~~~~~~~~~~~~~~~~
151man:lttng-create(1)::
152 {cmd_descr_create}.
153
154man:lttng-destroy(1)::
155 {cmd_descr_destroy}.
156
157man:lttng-load(1)::
158 {cmd_descr_load}.
159
160man:lttng-regenerate(1)::
161 {cmd_descr_regenerate}.
162
163man:lttng-save(1)::
164 {cmd_descr_save}.
165
166man:lttng-set-session(1)::
167 {cmd_descr_set_session}.
168
169
170Channels
171~~~~~~~~
172man:lttng-add-context(1)::
173 {cmd_descr_add_context}.
174
175man:lttng-disable-channel(1)::
176 {cmd_descr_disable_channel}.
177
178man:lttng-enable-channel(1)::
179 {cmd_descr_enable_channel}.
180
181
182Event rules
183~~~~~~~~~~~
184man:lttng-disable-event(1)::
185 {cmd_descr_disable_event}.
186
187man:lttng-enable-event(1)::
188 {cmd_descr_enable_event}.
189
190
191Status
192~~~~~~
193man:lttng-list(1)::
194 {cmd_descr_list}.
195
196man:lttng-status(1)::
197 {cmd_descr_status}.
198
199
200Control
201~~~~~~~
202man:lttng-snapshot(1)::
203 {cmd_descr_snapshot}.
204
205man:lttng-start(1)::
206 {cmd_descr_start}.
207
208man:lttng-stop(1)::
209 {cmd_descr_stop}.
210
211
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
225Resource tracking
226~~~~~~~~~~~~~~~~~
227man:lttng-track(1)::
228 {cmd_descr_track}.
229
230man:lttng-untrack(1)::
231 {cmd_descr_untrack}.
232
233
234Miscellaneous
235~~~~~~~~~~~~~
236man:lttng-help(1)::
237 {cmd_descr_help}.
238
239man:lttng-version(1)::
240 {cmd_descr_version}.
241
242man:lttng-view(1)::
243 {cmd_descr_view}.
244
245
246include::common-cmd-footer.txt[]
247
248
249SEE ALSO
250--------
251man:lttng-sessiond(8),
252man:lttng-relayd(8),
253man:lttng-crash(1),
254man:lttng-ust(3),
255man:babeltrace(1)
This page took 0.023845 seconds and 4 git commands to generate.