Docs: LTTNG(1) filtering is now supported by the kernel tracer
[lttng-tools.git] / doc / man / lttng.1
CommitLineData
516f6cbe 1.TH "LTTNG" "1" "May 13th, 2014" "" ""
6991b181
DG
2
3.SH "NAME"
94ffb05d 4lttng \- LTTng 2.x tracer control command line tool
6991b181
DG
5
6.SH "SYNOPSIS"
7
8.PP
6991b181 9lttng [OPTIONS] <COMMAND>
6991b181
DG
10.SH "DESCRIPTION"
11
12.PP
13The LTTng project aims at providing highly efficient tracing tools for Linux.
e256d661 14Its tracers help track down performance issues and debug problems
6991b181
DG
15involving multiple concurrent processes and threads. Tracing across multiple
16systems is also possible.
17
fa072eae 18The \fBlttng\fP command line tool from the lttng-tools package is used to control
e256d661
JG
19both kernel and user-space tracing. Every interaction with the tracer should
20be done by this tool or by the liblttng-ctl library provided by the lttng-tools
6991b181
DG
21package.
22
23LTTng uses a session daemon (lttng-sessiond(8)), acting as a tracing registry,
50a3b92a 24which allows you to interact with multiple tracers (kernel and user-space)
6991b181
DG
25inside the same container, a tracing session. Traces can be gathered from the
26kernel and/or instrumented applications (lttng-ust(3)). Aggregating and reading
27those traces is done using the babeltrace(1) text viewer.
28
50a3b92a 29We introduce the notion of \fBtracing domains\fP which is essentially a type of
0e115563
DG
30tracer (kernel, user space, JUL, LOG4J or Python for now). In the future, we
31could see more tracer like for instance an hypervisor. For some commands,
32you'll need to specify on which domain the command operates (\-u, \-k, \-l, \-j
33or \-p). For instance, the kernel domain must be specified when enabling a
34kernel event.
50a3b92a 35
6991b181
DG
36In order to trace the kernel, the session daemon needs to be running as root.
37LTTng provides the use of a \fBtracing group\fP (default: tracing). Whomever is
38in that group can interact with the root session daemon and thus trace the
e256d661 39kernel. Session daemons can co-exist, meaning that you can have a session daemon
fa072eae 40running as Alice that can be used to trace her applications along side with a
e256d661 41root daemon or even a Bob daemon. We highly recommend starting the session
6991b181
DG
42daemon at boot time for stable and long term tracing.
43
274d6c5d
DG
44Each user-space application instrumented with lttng-ust(3) will automatically
45register with the root session daemon and its user session daemon. This allows
46each daemon to list the available traceable applications and tracepoints at any
47given moment (See the \fBlist\fP command).
6991b181
DG
48.SH "OPTIONS"
49
50.PP
c0fdca17 51This program follows the usual GNU command line syntax with long options starting with
6991b181
DG
52two dashes. Below is a summary of the available options.
53.PP
54
55.TP
c9e32613 56.BR "\-h, \-\-help"
6991b181
DG
57Show summary of possible options and commands.
58.TP
c0fdca17
JG
59.BR "\-V, \-\-version"
60Show version.
61.TP
c9e32613 62.BR "\-v, \-\-verbose"
6991b181 63Increase verbosity.
d829b38c 64Three levels of verbosity are available which are triggered by putting additional v to
fa072eae 65the option (\-vv or \-vvv)
6991b181 66.TP
c9e32613 67.BR "\-q, \-\-quiet"
6991b181
DG
68Suppress all messages (even errors).
69.TP
c9e32613 70.BR "\-g, \-\-group NAME"
6991b181
DG
71Set unix tracing group name. (default: tracing)
72.TP
c9e32613 73.BR "\-n, \-\-no-sessiond"
6991b181
DG
74Don't automatically spawn a session daemon.
75.TP
391b9c72 76.BR "\-\-sessiond\-path PATH"
6991b181
DG
77Set session daemon full binary path.
78.TP
c9e32613 79.BR "\-\-list\-options"
6991b181
DG
80Simple listing of lttng options.
81.TP
c9e32613 82.BR "\-\-list\-commands"
6991b181 83Simple listing of lttng commands.
ed43168a
JRJ
84.TP
85.BR "\-m, \-\-mi TYPE
86Machine interface
87
88TYPE supported: XML
89
90Machine interface (MI) mode converts the traditional pretty printing to a
91machine output syntax. MI mode provides a format change-resistant way to access
92information generated via the lttng command line.
93
94When using MI mode, the data is printed on \fBstdout\fP. Error and warning are
95printed on \fBstderr\fP with the pretty print default format.
96
97If any errors occur during the execution of a command, the return value of the
98command will be different than zero. In this case, lttng does NOT guarantee the
99syntax and data validity of the generated MI output.
100
101For XML output type, a schema definition (XSD) file used for validation can be
102found under src/common/mi_lttng.xsd
103
6991b181
DG
104.SH "COMMANDS"
105
812a5eb7 106.PP
ee2758e5 107\fBadd-context\fP [OPTIONS]
812a5eb7 108.RS
6991b181
DG
109Add context to event(s) and/or channel(s).
110
391b9c72
DG
111A context is basically extra information appended to a channel. For instance,
112you could ask the tracer to add the PID information for all events in a
113channel. You can also add performance monitoring unit counters (perf PMU) using
aa3514e9 114the perf kernel API.
6991b181 115
aa3514e9
MD
116For example, this command will add the context information 'prio' and two per-CPU
117perf counters (hardware branch misses and cache misses), to all events in the trace
6991b181
DG
118data output:
119
812a5eb7 120.nf
aa3514e9
MD
121# lttng add-context \-k \-t prio \-t perf:cpu:branch-misses \\
122 \-t perf:cpu:cache-misses
812a5eb7 123.fi
6991b181 124
c9e32613 125Please take a look at the help (\-h/\-\-help) for a detailed list of available
6991b181
DG
126contexts.
127
aa3514e9
MD
128Perf counters are available as per-CPU ("perf:cpu:...") and per-thread
129("perf:thread:...") counters. Currently, per-CPU counters can only be
130used with the kernel tracing domain, and per-thread counters can only be
131used with the UST tracing domain.
132
bd337b98
DG
133If no channel is given (\-c), the context is added to all channels that were
134already enabled. If the session has no channel, a default channel is created.
31ea4846 135Otherwise the context will be added only to the given channel (\-c).
6991b181 136
c9e32613 137If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181 138file.
6991b181
DG
139
140.B OPTIONS:
141
812a5eb7
MD
142.TP
143.BR "\-h, \-\-help"
144Show summary of possible options and commands.
145.TP
146.BR "\-s, \-\-session NAME"
147Apply on session name.
148.TP
149.BR "\-c, \-\-channel NAME"
150Apply on channel name.
151.TP
152.BR "\-k, \-\-kernel"
153Apply for the kernel tracer
154.TP
155.BR "\-u, \-\-userspace"
156Apply for the user-space tracer
157.TP
158.BR "\-t, \-\-type TYPE"
159Context type. You can repeat this option on the command line. Please
160use "lttng add-context \-h" to list all available types.
161.RE
162.PP
6991b181 163
22019883
MD
164.PP
165\fBcalibrate\fP [OPTIONS]
166.RS
6991b181
DG
167Quantify LTTng overhead
168
169The LTTng calibrate command can be used to find out the combined average
170overhead of the LTTng tracer and the instrumentation mechanisms used. This
171overhead can be calibrated in terms of time or using any of the PMU performance
172counter available on the system.
173
174For now, the only calibration implemented is that of the kernel function
175instrumentation (kretprobes).
176
177* Calibrate kernel function instrumentation
178
179Let's use an example to show this calibration. We use an i7 processor with 4
180general-purpose PMU registers. This information is available by issuing dmesg,
181looking for "generic registers".
182
183This sequence of commands will gather a trace executing a kretprobe hooked on
184an empty function, gathering PMU counters LLC (Last Level Cache) misses
c9e32613 185information (see lttng add-context \-\-help to see the list of available PMU
6991b181
DG
186counters).
187
22019883 188.nf
6991b181 189# lttng create calibrate-function
22019883
MD
190# lttng enable-event calibrate \-\-kernel \\
191 \-\-function lttng_calibrate_kretprobe
aa3514e9
MD
192# lttng add-context \-\-kernel \-t perf:cpu:LLC-load-misses \\
193 \-t perf:cpu:LLC-store-misses \\
194 \-t perf:cpu:LLC-prefetch-misses
6991b181
DG
195# lttng start
196# for a in $(seq 1 10); do \\
c9e32613 197 lttng calibrate \-\-kernel \-\-function;
6991b181
DG
198 done
199# lttng destroy
22019883
MD
200# babeltrace $(ls \-1drt ~/lttng-traces/calibrate-function-* \\
201 | tail \-n 1)
202.fi
6991b181
DG
203
204The output from babeltrace can be saved to a text file and opened in a
205spreadsheet (e.g. oocalc) to focus on the per-PMU counter delta between
206consecutive "calibrate_entry" and "calibrate_return" events. Note that these
207counters are per-CPU, so scheduling events would need to be present to account
208for migration between CPU. Therefore, for calibration purposes, only events
209staying on the same CPU must be considered.
210
211The average result, for the i7, on 10 samples:
212
22019883 213.nf
6991b181
DG
214 Average Std.Dev.
215perf_LLC_load_misses: 5.0 0.577
216perf_LLC_store_misses: 1.6 0.516
217perf_LLC_prefetch_misses: 9.0 14.742
22019883 218.fi
6991b181
DG
219
220As we can notice, the load and store misses are relatively stable across runs
221(their standard deviation is relatively low) compared to the prefetch misses.
222We can conclude from this information that LLC load and store misses can be
223accounted for quite precisely, but prefetches within a function seems to behave
224too erratically (not much causality link between the code executed and the CPU
225prefetch activity) to be accounted for.
6991b181
DG
226
227.B OPTIONS:
228
22019883
MD
229.TP
230.BR "\-h, \-\-help"
231Show summary of possible options and commands.
232.TP
233.BR "\-k, \-\-kernel"
234Apply for the kernel tracer
235.TP
236.BR "\-u, \-\-userspace"
237Apply for the user-space tracer
238.TP
239.BR "\-\-function"
240Dynamic function entry/return probe (default)
241.RE
242.PP
6991b181 243
ee2758e5 244.PP
feb3ca56 245\fBcreate\fP [NAME] [OPTIONS]
ee2758e5 246.RS
6991b181
DG
247Create tracing session.
248
249A tracing session contains channel(s) which contains event(s). It is domain
e256d661 250agnostic, meaning that channels and events can be enabled for the
6991b181
DG
251user-space tracer and/or the kernel tracer. It acts like a container
252aggregating multiple tracing sources.
253
254On creation, a \fB.lttngrc\fP file is created in your $HOME directory
255containing the current session name. If NAME is omitted, a session name is
fa072eae 256automatically created having this form: 'auto-yyyymmdd-hhmmss'.
6991b181 257
c9e32613 258If no \fB\-o, \-\-output\fP is specified, the traces will be written in
6991b181 259$HOME/lttng-traces.
feb0f3e5
AM
260
261The $HOME environment variable can be overridden by defining the environment
262variable LTTNG_HOME. This is useful when the user running the commands has
263a non-writeable home directory.
6991b181 264
1c1c3634
DG
265The session name MUST NOT contain the character '/'.
266
6991b181
DG
267.B OPTIONS:
268
ee2758e5
MD
269.TP
270.BR "\-h, \-\-help"
271Show summary of possible options and commands.
272.TP
273.BR "\-\-list-options"
274Simple listing of options
275.TP
276.BR "\-o, \-\-output PATH"
277Specify output path for traces
278.TP
96fe6b8d
DG
279.BR "\-\-no-output"
280Traces will not be output
281.TP
ee2758e5 282.BR "\-\-snapshot"
96fe6b8d
DG
283Set the session in snapshot mode. Created in no-output mode and uses the
284URL, if one is specified, as the default snapshot output. Every channel will be set
ee2758e5 285in overwrite mode and with mmap output (splice not supported).
0794f51b 286.TP
d73c5802 287.BR "\-\-live [USEC]"
eb82f91d 288Set the session exclusively in live mode. The parameter is the delay in micro
0794f51b
DG
289seconds before the data is flushed and streamed. The live mode allows you to
290stream the trace and view it while it's being recorded by any tracer. For that,
291you need a lttng-relayd and this session requires a network URL (\-U or
d73c5802
DG
292\-C/\-D). If no USEC nor URL is provided, the default is to use a timer value
293set to 1000000 and the network URL set to net://127.0.0.1.
0794f51b
DG
294
295To read a live session, you can use babeltrace(1) or the live streaming
296protocol in doc/live-reading-protocol.txt. Here is an example:
297
298.nf
299$ lttng-relayd -o /tmp/lttng
300$ lttng create --live 200000 -U net://localhost
301$ lttng enable-event -a --userspace
302$ lttng start
303.fi
304
305After the start, you'll be able to read the events while they are being
306recorded in /tmp/lttng.
6b8f2e64 307
d7ba1388
MD
308.TP
309.BR "\-\-shm-path PATH"
310
311Path where shared memory holding buffers should be created. Useful
6a9a8e6a
JG
312when used with PRAMFS or other persistent memory filesystems to extract
313trace data in the event of a crash requiring a reboot.
d7ba1388 314
464bd4b0
JR
315See the \fBlttng-crash(1)\fP utility for more information on crash recovery.
316
ee2758e5
MD
317.TP
318.BR "\-U, \-\-set-url=URL"
319Set URL for the consumer output destination. It is persistent for the
320session lifetime. Redo the command to change it. This will set both data
321and control URL for network.
322.TP
323.BR "\-C, \-\-ctrl-url=URL"
324Set control path URL. (Must use -D also)
325.TP
326.BR "\-D, \-\-data-url=URL"
327Set data path URL. (Must use -C also)
328.PP
6b8f2e64
DG
329Using these options, each API call can be controlled individually. For
330instance, \-C does not enable the consumer automatically. You'll need the \-e
331option for that.
332
785d2d0d
DG
333.B URL FORMAT:
334
335proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH]
336
337Supported protocols are (proto):
ee2758e5
MD
338.TP
339.BR "file://..."
340Local filesystem full path.
785d2d0d 341
ee2758e5
MD
342.TP
343.BR "net://..."
344This will use the default network transport layer which is TCP for both
345control (PORT1) and data port (PORT2). The default ports are
346respectively 5342 and 5343. Note that net[6]:// is not yet supported.
785d2d0d 347
ee2758e5
MD
348.TP
349.BR "tcp[6]://..."
350Can only be used with -C and -D together
785d2d0d
DG
351
352NOTE: IPv6 address MUST be enclosed in brackets '[]' (rfc2732)
6b8f2e64
DG
353
354.B EXAMPLES:
355
ee2758e5 356.nf
6b8f2e64 357# lttng create -U net://192.168.1.42
ee2758e5 358.fi
6b8f2e64
DG
359Uses TCP and default ports for the given destination.
360
ee2758e5 361.nf
6b8f2e64 362# lttng create -U net6://[fe80::f66d:4ff:fe53:d220]
ee2758e5 363.fi
6b8f2e64
DG
364Uses TCP, default ports and IPv6.
365
ee2758e5 366.nf
6b8f2e64 367# lttng create s1 -U net://myhost.com:3229
6991b181 368.fi
ee2758e5
MD
369Create session s1 and set its consumer to myhost.com on port 3229 for control.
370.RE
371.PP
6991b181 372
f2b14ef1
MD
373.PP
374\fBdestroy\fP [NAME] [OPTIONS]
375.RS
6991b181
DG
376Teardown tracing session
377
378Free memory on the session daemon and tracer side. It's gone!
379
380If NAME is omitted, the session name is taken from the .lttngrc file.
6991b181
DG
381
382.B OPTIONS:
383
f2b14ef1
MD
384.TP
385.BR "\-h, \-\-help"
386Show summary of possible options and commands.
387.TP
388.BR "\-a, \-\-all"
389Destroy all sessions
390.TP
391.BR "\-\-list-options"
392Simple listing of options
393.RE
394.PP
6991b181 395
05be3802
MD
396.PP
397\fBenable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
398.RS
6991b181
DG
399Enable tracing channel
400
004f3466
DG
401To enable an event, you must enable both the event and the channel that
402contains it.
b883c01b 403
c9e32613 404If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181 405file.
7972aab2 406
05be3802
MD
407Exactly one of \-k or -u must be specified.
408
7972aab2 409It is important to note that if a certain type of buffers is used, the session
bd337b98 410will be set with that type and all other subsequent channel needs to have the
7972aab2 411same type.
bd337b98 412
d2f11c4a
DG
413Note that once the session has been started and enabled on the tracer side,
414it's not possible anymore to enable a new channel for that session.
6991b181
DG
415
416.B OPTIONS:
417
05be3802
MD
418.TP
419.BR "\-h, \-\-help"
420Show this help
421.TP
422.BR "\-\-list-options"
423Simple listing of options
424.TP
425.BR "\-s, \-\-session NAME"
426Apply on session name
427.TP
428.BR "\-k, \-\-kernel"
429Apply to the kernel tracer
430.TP
431.BR "\-u, \-\-userspace"
432Apply to the user-space tracer
433.TP
434.BR "\-\-discard"
435Discard event when subbuffers are full (default)
436.TP
437.BR "\-\-overwrite"
33fbd469
DG
438Flight recorder mode: overwrites events when subbuffers are full. The
439number of subbuffer must be 2 or more.
05be3802
MD
440.TP
441.BR "\-\-subbuf-size SIZE"
442Subbuffer size in bytes {+k,+M,+G}.
443(default UST uid: 131072, UST pid: 4096, kernel: 262144, metadata: 4096)
444Rounded up to the next power of 2.
445
446The minimum subbuffer size, for each tracer, is the max value between
447the default above and the system page size. You can issue this command
448to get the current page size on your system: \fB$ getconf PAGE_SIZE\fP
449.TP
450.BR "\-\-num-subbuf NUM"
451Number of subbuffers. (default UST uid: 4, UST pid: 4, kernel: 4,
452metadata: 2) Rounded up to the next power of 2.
453.TP
454.BR "\-\-switch-timer USEC"
455Switch subbuffer timer interval in µsec.
456(default UST uid: 0, UST pid: 0, kernel: 0, metadata: 0)
457.TP
458.BR "\-\-read-timer USEC"
459Read timer interval in µsec.
460(default UST uid: 0, UST pid: 0, kernel: 200000, metadata: 0)
461.TP
462.BR "\-\-output TYPE"
463Channel output type. Possible values: mmap, splice
464(default UST uid: mmap, UST pid: mmap, kernel: splice, metadata: mmap)
465.TP
466.BR "\-\-buffers-uid"
467Use per UID buffer (\-u only). Buffers are shared between applications
468that have the same UID.
469.TP
470.BR "\-\-buffers-pid"
471Use per PID buffer (\-u only). Each application has its own buffers.
472.TP
473.BR "\-\-buffers-global"
474Use shared buffer for the whole system (\-k only)
475.TP
476.BR "\-C, \-\-tracefile-size SIZE"
477Maximum size of each tracefile within a stream (in bytes).
4780 means unlimited. (default: 0)
c0684a0d 479Note: traces generated with this option may inaccurately report
a10f04ad 480discarded events as of CTF 1.8.
05be3802
MD
481.TP
482.BR "\-W, \-\-tracefile-count COUNT"
483Used in conjunction with \-C option, this will limit the number of files
484created to the specified count. 0 means unlimited. (default: 0)
1624d5b7
JD
485
486.B EXAMPLES:
487
05be3802
MD
488.nf
489$ lttng enable-channel -k -C 4096 -W 32 chan1
490.fi
e256d661 491For each stream, the maximum size of each trace file will be 4096 bytes and
cea28771 492there will be a maximum of 32 different files. The file count is appended after
1624d5b7
JD
493the stream number as seen in the following example. The last trace file is
494smaller than 4096 since it was not completely filled.
495
05be3802 496.nf
1624d5b7
JD
497 ~/lttng-traces/[...]/chan1_0_0 (4096)
498 ~/lttng-traces/[...]/chan1_0_1 (4096)
499 ~/lttng-traces/[...]/chan1_0_2 (3245)
500 ~/lttng-traces/[...]/chan1_1_0 (4096)
501 ...
05be3802 502.fi
1624d5b7 503
05be3802
MD
504.nf
505$ lttng enable-channel -k -C 4096
506.fi
1624d5b7
JD
507This will create trace files of 4096 bytes and will create new ones as long as
508there is data available.
05be3802
MD
509.RE
510.PP
6991b181 511
6a240cd9
MD
512.PP
513\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]
514.RS
6991b181
DG
515Enable tracing event
516
c9e32613 517A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is
6991b181 518omitted, a default channel named '\fBchannel0\fP' is created and the event is
85076754
MD
519added to it. If \fB\-c, \-\-channel\fP is omitted, but a non-default
520channel already exists within the session, an error is returned. For the
521user-space tracer, using \fB\-a, \-\-all\fP is the same as using the
522wildcard "*".
6991b181 523
c9e32613 524If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181 525file.
6991b181
DG
526
527.B OPTIONS:
528
6a240cd9
MD
529.TP
530.BR "\-h, \-\-help"
531Show summary of possible options and commands.
532.TP
533.BR "\-\-list-options"
534Simple listing of options
535.TP
536.BR "\-s, \-\-session NAME"
537Apply on session name
538.TP
539.BR "\-c, \-\-channel NAME"
540Apply on channel name
541.TP
542.BR "\-a, \-\-all"
e256d661 543Enable all tracepoints and syscalls. This actually enables a single
6a240cd9
MD
544wildcard event "*".
545.TP
546.BR "\-k, \-\-kernel"
547Apply for the kernel tracer
548.TP
549.BR "\-u, \-\-userspace"
550Apply for the user-space tracer
551.TP
bed69e7d
DG
552.BR "\-j, \-\-jul"
553Apply for Java application using Java Util Logging interface (JUL)
554.TP
222e4eab
DG
555.BR "\-l, \-\-log4j"
556Apply for Java application using LOG4J
557.TP
0e115563
DG
558.BR "\-p, \-\-python"
559Apply for Python application using the logging module.
560.TP
6a240cd9 561.BR "\-\-tracepoint"
e256d661 562Tracepoint event (default). Userspace tracer supports wildcards at the end
6a240cd9
MD
563of string. Don't forget to quote to deal with bash expansion.
564e.g.:
6991b181 565.nf
6991b181
DG
566 "*"
567 "app_component:na*"
6991b181 568.fi
6a240cd9
MD
569.TP
570.BR "\-\-loglevel NAME"
571Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h).
f9e8873b
DG
572For the JUL domain, the loglevel ranges are detailed with the \-\-help
573option thus starting from SEVERE to FINEST.
999ee001
DG
574For the LOG4J domain, loglevels range from FATAL to TRACE which are also
575detailed in the help.
0e115563
DG
576For the Python domain, loglevels range from CRITICAL to DEBUG which are
577detailed in the help as well.
6a240cd9
MD
578.TP
579.BR "\-\-loglevel-only NAME"
580Tracepoint loglevel (only this loglevel).
581The loglevel or loglevel-only options should be combined with a
582tracepoint name or tracepoint wildcard.
583.TP
584.BR "\-\-probe (addr | symbol | symbol+offset)"
585Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...)
586or hexadecimal (0xNNN...)
587.TP
588.BR "\-\-function (addr | symbol | symbol+offset)"
589Dynamic function entry/return probe. Addr and offset can be octal
590(0NNN...), decimal (NNN...) or hexadecimal (0xNNN...)
591.TP
592.BR "\-\-syscall"
593System call event. Enabling syscalls tracing (kernel tracer), you will
594not be able to disable them with disable-event. This is a known
627dbfd8
CB
595limitation. You can disable the entire channel to do the trick. Also note
596that per-syscall selection is not supported yet. Use with "-a" to enable
597all syscalls.
6a240cd9
MD
598.TP
599.BR "\-\-filter 'expression'"
600Set a filter on a newly enabled event. Filter expression on event
e256d661
JG
601fields and context. The event will be recorded if the filter's
602expression evaluates to TRUE. Only specify on first activation of a
603given event within a session.
604Specifying a filter is only allowed when enabling events within a session before
6a240cd9
MD
605tracing is started. If the filter fails to link with the event
606within the traced domain, the event will be discarded.
6a240cd9
MD
607
608Expression examples:
609
610.nf
611 'intfield > 500 && intfield < 503'
612 '(strfield == "test" || intfield != 10) && intfield > 33'
613 'doublefield > 1.1 && intfield < 5.3'
614.fi
615
616Wildcards are allowed at the end of strings:
617 'seqfield1 == "te*"'
618In string literals, the escape character is a '\\'. Use '\\*' for
e256d661
JG
619the '*' character, and '\\\\' for the '\\' character sequence. Wildcard
620matches any sequence of characters, including an empty sub-string
621(matches 0 or more characters).
6a240cd9 622
e256d661
JG
623Context information can be used for filtering. The examples below shows
624usage of context filtering on the process name (using a wildcard), process ID
625range, and unique thread ID. The process and thread IDs of
6a240cd9
MD
626running applications can be found under columns "PID" and "LWP" of the
627"ps -eLf" command.
628
629.nf
630 '$ctx.procname == "demo*"'
631 '$ctx.vpid >= 4433 && $ctx.vpid < 4455'
632 '$ctx.vtid == 1234'
633.fi
634
11139b74
DG
635Context information is available to all filters whether or not the add-context
636command has been used to add it to the event's channel, as long as the context
637field exists for that domain. For example, the filter examples given above will
638never fail to link: no add-context is required for the event's channel.
639
bccd20a3
JI
640.TP
641.BR "\-x, \-\-exclude LIST"
642Add exclusions to UST tracepoints:
643Events that match any of the items in the comma-separated LIST are not
644enabled, even if they match a wildcard definition of the event.
645
646This option is also applicable with the \fB\-a, \-\-all\fP option,
647in which case all UST tracepoints are enabled except the ones whose
648names match any of the items in LIST.
6a240cd9
MD
649.RE
650.PP
6991b181 651
272c6a17
MD
652.PP
653\fBdisable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
654.RS
6991b181
DG
655Disable tracing channel
656
e256d661 657Disabling a channel disables the tracing of all of the channel's events. A channel
5368d366 658can be re-enabled by calling \fBlttng enable-channel NAME\fP again.
6991b181 659
c9e32613 660If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181 661file.
6991b181
DG
662
663.B OPTIONS:
664
272c6a17
MD
665.TP
666.BR "\-h, \-\-help"
667Show summary of possible options and commands.
668.TP
669.BR "\-\-list-options"
670Simple listing of options
671.TP
672.BR "\-s, \-\-session NAME"
673Apply on session name
674.TP
675.BR "\-k, \-\-kernel"
676Apply for the kernel tracer
677.TP
678.BR "\-u, \-\-userspace"
679Apply for the user-space tracer
680.RE
681.PP
6991b181 682
c138a39b
MD
683.PP
684\fBdisable-event\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
685.RS
6991b181
DG
686Disable tracing event
687
688The event, once disabled, can be re-enabled by calling \fBlttng enable-event
689NAME\fP again.
690
c9e32613 691If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181 692file.
6991b181 693
85076754
MD
694If \fB\-c, \-\-channel\fP is omitted, the default channel name is used.
695If \fB\-c, \-\-channel\fP is omitted, but a non-default channel already
696exists within the session, an error is returned.
697
6991b181
DG
698.B OPTIONS:
699
c138a39b
MD
700.TP
701.BR "\-h, \-\-help"
702Show summary of possible options and commands.
703.TP
704.BR "\-\-list-options"
705Simple listing of options
706.TP
707.BR "\-s, \-\-session NAME"
708Apply on session name
709.TP
85076754
MD
710.BR "\-c, \-\-channel NAME"
711Apply on channel name
712.TP
c138a39b
MD
713.BR "\-a, \-\-all-events"
714Disable all events. This does NOT disable "*" but rather every known
715events of the session.
716.TP
717.BR "\-k, \-\-kernel"
718Apply for the kernel tracer
719.TP
720.BR "\-u, \-\-userspace"
721Apply for the user-space tracer
bed69e7d
DG
722.TP
723.BR "\-j, \-\-jul"
724Apply for Java application using Java Util Logging interface (JUL)
222e4eab
DG
725.TP
726.BR "\-l, \-\-log4j"
727Apply for Java application using LOG4J
0e115563
DG
728.TP
729.BR "\-p, \-\-python"
730Apply for Python application using the logging module.
c138a39b
MD
731.RE
732.PP
6991b181 733
747361fe
MD
734.PP
735\fBlist\fP [OPTIONS] [SESSION [SESSION OPTIONS]]
736.RS
c9e32613 737List tracing session information.
6991b181
DG
738
739With no arguments, it will list available tracing session(s).
740
fa072eae
YB
741With the session name, it will display the details of the session including
742the trace file path, the associated channels and their state (activated
d829b38c 743and deactivated), the activated events and more.
fa072eae 744
c9e32613 745With \-k alone, it will list all available kernel events (except the system
6991b181 746calls events).
bed69e7d
DG
747With \-j alone, the available JUL event from registered application will be
748list. The event corresponds to the Logger name in the Java JUL application.
999ee001
DG
749With \-l alone, the available LOG4J event from registered application will be
750list. The event corresponds to the Logger name in the Java LOG4J application.
0e115563
DG
751With \-p alone, the available Python event from registered application will be
752list. The event corresponds to the Logger name in the Python application.
c9e32613
DG
753With \-u alone, it will list all available user-space events from registered
754applications. Here is an example of 'lttng list \-u':
6991b181 755
747361fe 756.nf
6991b181
DG
757PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello
758 ust_tests_hello:tptest_sighandler (type: tracepoint)
759 ust_tests_hello:tptest (type: tracepoint)
747361fe 760.fi
6991b181
DG
761
762You can now enable any event listed by using the name :
763\fBust_tests_hello:tptest\fP.
6991b181
DG
764
765.B OPTIONS:
766
747361fe
MD
767.TP
768.BR "\-h, \-\-help"
769Show summary of possible options and commands.
770.TP
771.BR "\-\-list-options"
772Simple listing of options
773.TP
774.BR "\-k, \-\-kernel"
775Select kernel domain
776.TP
777.BR "\-u, \-\-userspace"
778Select user-space domain.
bed69e7d
DG
779.TP
780.BR "\-j, \-\-jul"
781Apply for Java application using JUL
782.TP
222e4eab
DG
783.BR "\-l, \-\-log4j"
784Apply for Java application using LOG4J
0e115563
DG
785.TP
786.BR "\-p, \-\-python"
787Apply for Python application using the logging module.
788.TP
bed69e7d
DG
789.BR "\-f, \-\-fields"
790List event fields
6991b181 791
747361fe 792.PP
6b8f2e64
DG
793.B SESSION OPTIONS:
794
747361fe
MD
795.TP
796.BR "\-c, \-\-channel NAME"
797List details of a channel
798.TP
799.BR "\-d, \-\-domain"
800List available domain(s)
801.RE
802.PP
6991b181 803
516f6cbe
JG
804.PP
805\fBload\fP [OPTIONS] [NAME]
806.RS
807Load tracing session configuration
808
809If NAME is omitted, all session configurations found in both the user's session
bd88d988 810configuration directory (default: ~/.lttng/sessions/) and the system session
cf53c06d
DG
811configuration directory (default: /etc/lttng/sessions/) will be loaded. Note
812that the sessions in the user directory are loaded first and then the system
813wide directory are loaded.
516f6cbe
JG
814
815.B OPTIONS:
816
817.TP
818.BR "\-h, \-\-help"
819Show summary of possible options and commands.
820.TP
821.BR "\-a, \-\-all"
822Load all session configurations (default).
823.TP
824.BR "\-i, \-\-input-path PATH"
bd88d988
DG
825Specify the input path for session configurations. This overrides the default
826session configuration directory.
516f6cbe
JG
827.TP
828.BR "\-f, -\-force"
829Overwrite current session configuration(s) if a session of the same name
830already exists.
831.RE
832.PP
833
834.PP
835\fBsave\fP [OPTIONS] [SESSION]
836.RS
837Save tracing session configuration
838
839If SESSION is omitted, all session configurations will be saved to individual
553067af 840\fB.lttng\fP files under the user's session configuration directory (default:
bd88d988
DG
841~/.lttng/sessions/). The default session configuration file naming scheme is
842\fBSESSION.lttng\fP.
516f6cbe 843
cf53c06d
DG
844For instance, a user in the tracing group saving a session from a root session
845daemon will save it in her/his user directory.
846
516f6cbe
JG
847.B OPTIONS:
848
849.TP
850.BR "\-h, \-\-help"
851Show summary of possible options and commands.
852.TP
853.BR "\-a, \-\-all"
854Save all session configurations (default).
855.TP
856.BR "\-o, \-\-output-path PATH"
553067af
DG
857Specify the output path for saved sessions. This overrides the default session
858configuration directory.
516f6cbe
JG
859.TP
860.BR "\-f, -\-force"
861Overwrite session configuration file if session name clashes.
862.RE
863.PP
864
7c96a096
MD
865.PP
866\fBset-session\fP NAME [OPTIONS]
867.RS
6991b181
DG
868Set current session name
869
870Will change the session name in the .lttngrc file.
6991b181
DG
871
872.B OPTIONS:
873
7c96a096
MD
874.TP
875.BR "\-h, \-\-help"
876Show summary of possible options and commands.
877.TP
878.BR "\-\-list-options"
879Simple listing of options
880.RE
881.PP
6991b181 882
8df3bfe9
MD
883.PP
884\fBsnapshot\fP [OPTIONS] ACTION
885.RS
b872baea 886Snapshot command for LTTng session.
b872baea
DG
887
888.B OPTIONS:
889
8df3bfe9
MD
890.TP
891.BR "\-h, \-\-help"
892Show summary of possible options and commands.
893.TP
894.BR "\-\-list-options"
895Simple listing of options
b872baea 896
8df3bfe9 897.PP
b872baea
DG
898.B ACTION:
899
8df3bfe9 900.TP
b872baea
DG
901\fBadd-output\fP [-m <SIZE>] [-s <NAME>] [-n <NAME>] <URL> | -C <URL> -D <URL>
902
88743287 903Setup and add a snapshot output for a session. Output is the destination
b872baea
DG
904where the snapshot will be sent. Only one output is permitted. To change it,
905you'll need to delete it and add back the new one.
906
8df3bfe9 907.TP
b872baea
DG
908\fBdel-output\fP ID | NAME [-s <NAME>]
909
88743287
JG
910Delete an output for a session using the output's ID. You can either specify the
911output by name or use its ID as returned by the list-output command.
b872baea 912
8df3bfe9 913.TP
b872baea
DG
914\fBlist-output\fP [-s <NAME>]
915
916List the output of a session. Attributes of the output are printed.
917
8df3bfe9 918.TP
b872baea
DG
919\fBrecord\fP [-m <SIZE>] [-s <NAME>] [-n <NAME>] [<URL> | -C <URL> -D <URL>]
920
921Snapshot a session's buffer(s) for all domains. If an URL is specified, it is
922used instead of a previously added output. Specifying only a name or/and a max
923size will override the current output values. For instance, you can record a
924snapshot with a custom maximum size or with a different name.
925
8df3bfe9 926.nf
1ac1098f 927$ lttng snapshot add-output -n mysnapshot file:///data/snapshot
b872baea
DG
928[...]
929$ lttng snapshot record -n new_name_snapshot
8df3bfe9 930.fi
b872baea
DG
931
932The above will create a snapshot in /data/snapshot/new_name_snapshot* directory
933rather then in mysnapshot*/
b872baea 934
8df3bfe9
MD
935.PP
936.B DETAILED ACTION OPTIONS
b872baea 937
8df3bfe9
MD
938.TP
939.BR "\-s, \-\-session NAME"
940Apply to session name.
941.TP
942.BR "\-n, \-\-name NAME"
943Name of the snapshot's output.
944.TP
945.BR "\-m, \-\-max-size SIZE"
eb82f91d 946Maximum size in bytes of the snapshot. The maximum size does not include the
a8f307d8
SM
947metadata file. Human readable format is accepted: {+k,+M,+G}. For instance,
948\-\-max-size 5M
8df3bfe9
MD
949.TP
950.BR "\-C, \-\-ctrl-url URL"
951Set control path URL. (Must use -D also)
952.TP
953.BR "\-D, \-\-data-url URL"
954Set data path URL. (Must use -C also)
955.RE
956.PP
b872baea 957
afb8ca1b
MD
958.PP
959\fBstart\fP [NAME] [OPTIONS]
960.RS
6991b181
DG
961Start tracing
962
963It will start tracing for all tracers for a specific tracing session.
6991b181 964If NAME is omitted, the session name is taken from the .lttngrc file.
6991b181
DG
965
966.B OPTIONS:
967
afb8ca1b
MD
968.TP
969.BR "\-h, \-\-help"
970Show summary of possible options and commands.
971.TP
972.BR "\-\-list-options"
973Simple listing of options
974.RE
975.PP
6991b181 976
6c09bfdb
MD
977.PP
978\fBstop\fP [NAME] [OPTIONS]
979.RS
6991b181
DG
980Stop tracing
981
391b9c72
DG
982It will stop tracing for all tracers for a specific tracing session. Before
983returning, the command checks for data availability meaning that it will wait
984until the trace is readable for the session. Use \-\-no-wait to avoid this
985behavior.
6991b181
DG
986
987If NAME is omitted, the session name is taken from the .lttngrc file.
6991b181
DG
988
989.B OPTIONS:
990
6c09bfdb
MD
991.TP
992.BR "\-h, \-\-help"
993Show summary of possible options and commands.
994.TP
995.BR "\-\-list-options"
996Simple listing of options
3a7a166e
MJ
997.TP
998.BR "\-\-no-wait"
6c09bfdb
MD
999Don't wait for data availability.
1000.RE
1001.PP
6991b181 1002
5975c30a
MD
1003.PP
1004\fBversion\fP
1005.RS
6991b181 1006Show version information
6991b181
DG
1007
1008.B OPTIONS:
1009
5975c30a
MD
1010.TP
1011.BR "\-h, \-\-help"
1012Show summary of possible options and commands.
1013.TP
1014.BR "\-\-list-options"
1015Simple listing of options
1016.RE
1017.PP
6991b181 1018
5b4c1410
MD
1019.PP
1020\fBview\fP [SESSION_NAME] [OPTIONS]
1021.RS
1022View traces of a tracing session. By default, the babeltrace viewer
1023will be used for text viewing. If SESSION_NAME is omitted, the session
1024name is taken from the .lttngrc file.
6991b181
DG
1025
1026.B OPTIONS:
1027
5b4c1410
MD
1028.TP
1029.BR "\-h, \-\-help"
1030Show this help
1031.TP
1032.BR "\-\-list-options"
1033Simple listing of options
1034.TP
1035.BR "\-t, \-\-trace-path PATH"
1036Trace directory path for the viewer
1037.TP
1038.BR "\-e, \-\-viewer CMD"
1039Specify viewer and/or options to use This will completely override the
1040default viewers so please make sure to specify the full command. The
1041trace directory path of the session will be appended at the end to the
1042arguments
1043.RE
1044.PP
6991b181 1045
999ee001
DG
1046.SH "JUL/LOG4J DOMAIN"
1047
1048This section explains the JUL and LOG4J domain where JUL stands for Java Util
1049Logging. You can use these by using the \fBliblttng-ust-<domain>-jni.so\fP from
1050the lttng-ust(3) project.
acf47627
DG
1051
1052The LTTng Java Agent uses JNI to link the UST tracer to the Java application
1053that uses the agent. Thus, it behaves similarly to the UST domain (\-u). When
999ee001
DG
1054enabling events, you enable a Logger name that will then be mapped to a default
1055UST tracepoint called \fBlttng_jul:<domain>_event\fP in the
1056\fBlttng_<domain>_channel\fP. Using the lttng-ctl API, any JUL/LOG4J events
1057must use the tracepoint event type (same as \-\-tracepoint).
acf47627 1058
999ee001
DG
1059Because of the default immutable channel, the \fBenable-channel\fP command CAN
1060NOT be used with the JUL and LOG4J domain thus not having any options.
acf47627 1061
999ee001
DG
1062Also, loglevels are supported. Use \fBlttng enable-event \-h\fP to list them.
1063Wildcards are NOT supported except the "*" meaning all events (same as \-a).
acf47627
DG
1064
1065Exactly like the UST domain, if the Java application has the same UID as you,
1066you can trace it. Same goes for the tracing group accessing root applications.
1067
999ee001
DG
1068Finally, you can list every Logger name that are available from registered
1069applications to the session daemon by using \fBlttng list \-j\fP or \fB\-l\fP.
acf47627 1070
999ee001 1071Here is an example on how to use the JUL domain.
acf47627
DG
1072
1073.nf
1074$ lttng list -j
1075[...]
1076$ lttng create aSession
1077$ lttng enable-event -s aSession -j MyCustomLoggerName
1078$ lttng start
1079.fi
1080
1081More information can be found in the lttng-ust documentation, see
1082java-util-logging.txt
1083.PP
1084
c206d957 1085.SH "EXIT VALUES"
b107a0b1 1086.PP
6b8f2e64
DG
1087On success 0 is returned and a positive value on error. Value of 1 means a command
1088error, 2 an undefined command, 3 a fatal error and 4 a command warning meaning that
1089something went wrong during the command.
c206d957 1090
6b8f2e64 1091Any other value above 10, please refer to
b107a0b1 1092.BR "<lttng/lttng-error.h>"
6b8f2e64
DG
1093for a detailed list or use lttng_strerror() to get a human readable string of
1094the error code.
c206d957 1095.PP
b107a0b1 1096
6991b181
DG
1097.SH "ENVIRONMENT VARIABLES"
1098
1099.PP
1100Note that all command line options override environment variables.
1101.PP
1102
1103.PP
05833633 1104.IP "LTTNG_SESSIOND_PATH"
c9e32613
DG
1105Allows one to specify the full session daemon binary path to lttng command line
1106tool. You can also use \-\-sessiond-path option having the same effect.
b107a0b1
MD
1107.PP
1108
516f6cbe
JG
1109.PP
1110.IP "LTTNG_SESSION_CONFIG_XSD_PATH"
1111Set the path in which the \fBsession.xsd\fP session configuration schema may be
1112found.
1113.PP
1114
6991b181 1115.SH "SEE ALSO"
6b8f2e64
DG
1116.BR babeltrace(1),
1117.BR lttng-ust(3),
1118.BR lttng-sessiond(8),
1119.BR lttng-relayd(8),
464bd4b0 1120.BR lttng-crash(1),
b107a0b1 1121
6991b181
DG
1122.SH "BUGS"
1123
b107a0b1 1124.PP
6991b181 1125If you encounter any issues or usability problem, please report it on our
6b8f2e64 1126mailing list <lttng-dev@lists.lttng.org> to help improve this project or
eb82f91d 1127at https://bugs.lttng.org which is a bug tracker.
b107a0b1
MD
1128.PP
1129
6991b181
DG
1130.SH "CREDITS"
1131
1132.PP
c9e32613 1133lttng is distributed under the GNU General Public License version 2. See the file
6991b181
DG
1134COPYING for details.
1135.PP
1136A Web site is available at http://lttng.org for more information on the LTTng
1137project.
1138.PP
1139You can also find our git tree at http://git.lttng.org.
1140.PP
1141Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
1142.PP
1143You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
1144.PP
1145.SH "THANKS"
1146
1147.PP
1148Thanks to Yannick Brosseau without whom this project would never have been so
1149lean and mean! Also thanks to the Ericsson teams working on tracing which
fa072eae 1150helped us greatly with detailed bug reports and unusual test cases.
6991b181
DG
1151
1152Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
1153maintainer) and Jon Bernard for our Debian packages.
1154
1155Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
1156Montreal for the LTTng journey.
c9e32613 1157.PP
6991b181
DG
1158.SH "AUTHORS"
1159
1160.PP
1161lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
1162David Goulet. More people have since contributed to it. It is currently
9b22d135 1163maintained by Jérémie Galarneau <jeremie.galarneau@efficios.com>.
6991b181 1164.PP
This page took 0.145343 seconds and 4 git commands to generate.