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