Fix: replace 'modprobe -l' by lsmod in kernel test
[lttng-tools.git] / doc / man / lttng.1
CommitLineData
6991b181
DG
1.TH "LTTNG" "1" "February 9, 2012" "" ""
2
3.SH "NAME"
4lttng \(em LTTng 2.0 tracer control command line tool
5
6.SH "SYNOPSIS"
7
8.PP
9.nf
10lttng [OPTIONS] <COMMAND>
11.fi
12.SH "DESCRIPTION"
13
14.PP
15The LTTng project aims at providing highly efficient tracing tools for Linux.
16It's tracers help tracking down performance issues and debugging problems
17involving multiple concurrent processes and threads. Tracing across multiple
18systems is also possible.
19
fa072eae 20The \fBlttng\fP command line tool from the lttng-tools package is used to control
6991b181
DG
21both kernel and user-space tracing. Every interactions with the tracer should
22be done by this tool or by the liblttng-ctl provided with the lttng-tools
23package.
24
25LTTng uses a session daemon (lttng-sessiond(8)), acting as a tracing registry,
26which permits you to interact with multiple tracers (kernel and user-space)
27inside the same container, a tracing session. Traces can be gathered from the
28kernel and/or instrumented applications (lttng-ust(3)). Aggregating and reading
29those traces is done using the babeltrace(1) text viewer.
30
31In order to trace the kernel, the session daemon needs to be running as root.
32LTTng provides the use of a \fBtracing group\fP (default: tracing). Whomever is
33in that group can interact with the root session daemon and thus trace the
34kernel. Session daemons can co-exist meaning that you can have a session daemon
fa072eae
YB
35running as Alice that can be used to trace her applications along side with a
36root daemon or even a Bob daemon. We highly recommend to start the session
6991b181
DG
37daemon at boot time for stable and long term tracing.
38
39Every user-space applications instrumented with lttng-ust(3), will
40automatically register to the session daemon. This feature gives you the
41ability to list available traceable applications and tracepoints on a per user
42basis. (See \fBlist\fP command).
43.SH "OPTIONS"
44
45.PP
46This program follow the usual GNU command line syntax with long options starting with
47two dashes. Below is a summary of the available options.
48.PP
49
50.TP
c9e32613 51.BR "\-h, \-\-help"
6991b181
DG
52Show summary of possible options and commands.
53.TP
c9e32613 54.BR "\-v, \-\-verbose"
6991b181 55Increase verbosity.
d829b38c 56Three levels of verbosity are available which are triggered by putting additional v to
fa072eae 57the option (\-vv or \-vvv)
6991b181 58.TP
c9e32613 59.BR "\-q, \-\-quiet"
6991b181
DG
60Suppress all messages (even errors).
61.TP
c9e32613 62.BR "\-g, \-\-group NAME"
6991b181
DG
63Set unix tracing group name. (default: tracing)
64.TP
c9e32613 65.BR "\-n, \-\-no-sessiond"
6991b181
DG
66Don't automatically spawn a session daemon.
67.TP
c9e32613 68.BR "\-\-sessiond\-path"
6991b181
DG
69Set session daemon full binary path.
70.TP
c9e32613 71.BR "\-\-list\-options"
6991b181
DG
72Simple listing of lttng options.
73.TP
c9e32613 74.BR "\-\-list\-commands"
6991b181
DG
75Simple listing of lttng commands.
76.SH "COMMANDS"
77
78.TP
79\fBadd-context\fP
80.nf
81Add context to event(s) and/or channel(s).
82
83A context is basically extra information appended to a channel or event. For
84instance, you could ask the tracer to add the PID information within the
85"sched_switch" kernel event. You can also add performance monitoring unit
86counters (perf PMU) using the perf kernel API).
87
88For example, this command will add the context information 'prio' and two perf
89counters (hardware branch misses and cache misses), to all events in the trace
90data output:
91
c9e32613 92# lttng add-context \-k \-t prio \-t perf:branch-misses \-t perf:cache-misses
6991b181 93
c9e32613 94Please take a look at the help (\-h/\-\-help) for a detailed list of available
6991b181
DG
95contexts.
96
c9e32613 97If no channel and no event is given (\-c/\-e), the context is added to all
6991b181 98channels (which applies automatically to all events in that channel). Otherwise
c9e32613 99the context will be added only to the channel (\-c) and/or event (\-e) indicated.
6991b181 100
c9e32613 101If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
102file.
103.fi
104
105.B OPTIONS:
106
107.nf
c9e32613 108\-h, \-\-help
6991b181 109 Show summary of possible options and commands.
c9e32613 110\-s, \-\-session NAME
6991b181 111 Apply on session name.
c9e32613 112\-c, \-\-channel NAME
6991b181 113 Apply on channel name.
c9e32613 114\-e, \-\-event NAME
6991b181 115 Apply on event name.
c9e32613 116\-k, \-\-kernel
6991b181 117 Apply for the kernel tracer
c9e32613 118\-u, \-\-userspace
6991b181 119 Apply for the user-space tracer
c9e32613 120\-t, \-\-type TYPE
6991b181 121 Context type. You can repeat this option on the command line. Please
c9e32613 122 use "lttng add-context \-h" to list all available types.
6991b181
DG
123.fi
124
125.IP
126
127.IP "\fBcalibrate\fP"
128.nf
129Quantify LTTng overhead
130
131The LTTng calibrate command can be used to find out the combined average
132overhead of the LTTng tracer and the instrumentation mechanisms used. This
133overhead can be calibrated in terms of time or using any of the PMU performance
134counter available on the system.
135
136For now, the only calibration implemented is that of the kernel function
137instrumentation (kretprobes).
138
139* Calibrate kernel function instrumentation
140
141Let's use an example to show this calibration. We use an i7 processor with 4
142general-purpose PMU registers. This information is available by issuing dmesg,
143looking for "generic registers".
144
145This sequence of commands will gather a trace executing a kretprobe hooked on
146an empty function, gathering PMU counters LLC (Last Level Cache) misses
c9e32613 147information (see lttng add-context \-\-help to see the list of available PMU
6991b181
DG
148counters).
149
150# lttng create calibrate-function
c9e32613
DG
151# lttng enable-event calibrate \-\-kernel \-\-function lttng_calibrate_kretprobe
152# lttng add-context \-\-kernel \-t perf:LLC-load-misses \-t perf:LLC-store-misses \\
153 \-t perf:LLC-prefetch-misses
6991b181
DG
154# lttng start
155# for a in $(seq 1 10); do \\
c9e32613 156 lttng calibrate \-\-kernel \-\-function;
6991b181
DG
157 done
158# lttng destroy
c9e32613 159# babeltrace $(ls \-1drt ~/lttng-traces/calibrate-function-* | tail \-n 1)
6991b181
DG
160
161The output from babeltrace can be saved to a text file and opened in a
162spreadsheet (e.g. oocalc) to focus on the per-PMU counter delta between
163consecutive "calibrate_entry" and "calibrate_return" events. Note that these
164counters are per-CPU, so scheduling events would need to be present to account
165for migration between CPU. Therefore, for calibration purposes, only events
166staying on the same CPU must be considered.
167
168The average result, for the i7, on 10 samples:
169
170 Average Std.Dev.
171perf_LLC_load_misses: 5.0 0.577
172perf_LLC_store_misses: 1.6 0.516
173perf_LLC_prefetch_misses: 9.0 14.742
174
175As we can notice, the load and store misses are relatively stable across runs
176(their standard deviation is relatively low) compared to the prefetch misses.
177We can conclude from this information that LLC load and store misses can be
178accounted for quite precisely, but prefetches within a function seems to behave
179too erratically (not much causality link between the code executed and the CPU
180prefetch activity) to be accounted for.
181.fi
182
183.B OPTIONS:
184
185.nf
c9e32613 186\-h, \-\-help
6991b181 187 Show summary of possible options and commands.
c9e32613 188\-k, \-\-kernel
6991b181 189 Apply for the kernel tracer
c9e32613 190\-u, \-\-userspace
6991b181 191 Apply for the user-space tracer
c9e32613 192\-\-function
6991b181
DG
193 Dynamic function entry/return probe (default)
194.fi
195
196.IP
197
198.IP "\fBcreate\fP [OPTIONS] [NAME]
199.nf
200Create tracing session.
201
202A tracing session contains channel(s) which contains event(s). It is domain
203agnostic meaning that you can enable channels and events for either the
204user-space tracer and/or the kernel tracer. It acts like a container
205aggregating multiple tracing sources.
206
207On creation, a \fB.lttngrc\fP file is created in your $HOME directory
208containing the current session name. If NAME is omitted, a session name is
fa072eae 209automatically created having this form: 'auto-yyyymmdd-hhmmss'.
6991b181 210
c9e32613 211If no \fB\-o, \-\-output\fP is specified, the traces will be written in
6991b181
DG
212$HOME/lttng-traces.
213.fi
214
215.B OPTIONS:
216
217.nf
c9e32613 218\-h, \-\-help
6991b181 219 Show summary of possible options and commands.
c9e32613 220\-\-list-options
6991b181 221 Simple listing of options
c9e32613 222\-o, \-\-output PATH
6991b181
DG
223 Specify output path for traces
224.fi
225
226.IP
227
228.IP "\fBdestroy\fP [OPTIONS] [NAME]"
229.nf
230Teardown tracing session
231
232Free memory on the session daemon and tracer side. It's gone!
233
234If NAME is omitted, the session name is taken from the .lttngrc file.
235.fi
236
237.B OPTIONS:
238
239.nf
c9e32613 240\-h, \-\-help
6991b181 241 Show summary of possible options and commands.
c9e32613 242\-\-list-options
6991b181
DG
243 Simple listing of options
244.fi
245
246.IP
247
248.IP "\fBenable-channel\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
249.nf
250Enable tracing channel
251
b883c01b
DG
252To enable event, you must first enable a channel which contains event(s).
253
c9e32613 254If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
255file.
256.fi
257
258.B OPTIONS:
259
260.nf
c9e32613 261\-h, \-\-help
6991b181 262 Show this help
c9e32613 263\-\-list-options
6991b181 264 Simple listing of options
c9e32613 265\-s, \-\-session
6991b181 266 Apply on session name
c9e32613 267\-k, \-\-kernel
6991b181 268 Apply to the kernel tracer
c9e32613 269\-u, \-\-userspace
6991b181
DG
270 Apply to the user-space tracer
271
c9e32613 272\-\-discard
6991b181 273 Discard event when subbuffers are full (default)
c9e32613 274\-\-overwrite
6991b181 275 Flight recorder mode : overwrites events when subbuffers are full
c9e32613 276\-\-subbuf-size
6991b181 277 Subbuffer size in bytes (default: 4096, kernel default: 262144)
c9e32613 278\-\-num-subbuf
d829b38c 279 Number of subbuffers (default: 4)
93e6c8a0 280 Needs to be a power of 2 for kernel and ust tracers
c9e32613 281\-\-switch-timer
6991b181 282 Switch subbuffer timer interval in usec (default: 0)
93e6c8a0 283 Needs to be a power of 2 for kernel and ust tracers
c9e32613 284\-\-read-timer
6991b181
DG
285 Read timer interval in usec (default: 200)
286.fi
287
288.IP
289
290.IP "\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
291.nf
292Enable tracing event
293
c9e32613 294A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is
6991b181 295omitted, a default channel named '\fBchannel0\fP' is created and the event is
c9e32613 296added to it. For the user-space tracer, using \fB\-a, \-\-all\fP is the same as
6991b181
DG
297using the wildcard "*".
298
c9e32613 299If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
300file.
301.fi
302
303.B OPTIONS:
304
305.nf
c9e32613 306\-h, \-\-help
6991b181 307 Show summary of possible options and commands.
c9e32613 308\-\-list-options
6991b181 309 Simple listing of options
c9e32613 310\-s, \-\-session
6991b181 311 Apply on session name
c9e32613 312\-c, \-\-channel
6991b181 313 Apply on channel name
c9e32613 314\-a, \-\-all
e08bff8d 315 Enable all tracepoints and syscalls
c9e32613 316\-k, \-\-kernel
6991b181 317 Apply for the kernel tracer
c9e32613 318\-u, \-\-userspace
6991b181
DG
319 Apply for the user-space tracer
320
c9e32613 321\-\-tracepoint
6991b181
DG
322 Tracepoint event (default)
323 - userspace tracer supports wildcards at end of string. Don't forget to
324 quote to deal with bash expansion.
325 e.g.:
326 "*"
327 "app_component:na*"
c9e32613 328\-\-loglevel
6991b181 329 Tracepoint loglevel
c9e32613 330\-\-probe [addr | symbol | symbol+offset]
6991b181
DG
331 Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...)
332 or hexadecimal (0xNNN...)
c9e32613 333\-\-function [addr | symbol | symbol+offset]
6991b181
DG
334 Dynamic function entry/return probe. Addr and offset can be octal
335 (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...)
c9e32613 336\-\-syscall
6991b181
DG
337 System call event
338 Enabling syscalls tracing (kernel tracer), you will not be able to disable them
339 with disable-event. This is a known limitation. You can disable the entire
340 channel to do the trick.
341.fi
342
c9e32613 343.IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
6991b181
DG
344.nf
345Disable tracing channel
346
347Disabling a channel makes all event(s) in that channel to stop tracing. You can
348enable it back by calling \fBlttng enable-channel NAME\fP again.
349
c9e32613 350If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
351file.
352.fi
353
354.B OPTIONS:
355
356.nf
c9e32613 357\-h, \-\-help
6991b181 358 Show summary of possible options and commands.
c9e32613 359\-\-list-options
6991b181 360 Simple listing of options
c9e32613 361\-s, \-\-session
6991b181 362 Apply on session name
c9e32613 363\-k, \-\-kernel
6991b181 364 Apply for the kernel tracer
c9e32613 365\-u, \-\-userspace
6991b181
DG
366 Apply for the user-space tracer
367.fi
368
c9e32613 369.IP "\fBdisable-event\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
6991b181
DG
370.nf
371Disable tracing event
372
373The event, once disabled, can be re-enabled by calling \fBlttng enable-event
374NAME\fP again.
375
c9e32613 376If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
377file.
378.fi
379
380.B OPTIONS:
381
382.nf
c9e32613 383\-h, \-\-help
6991b181 384 Show summary of possible options and commands.
c9e32613 385\-\-list-options
6991b181 386 Simple listing of options
c9e32613 387\-s, \-\-session
6991b181 388 Apply on session name
c9e32613 389\-k, \-\-kernel
6991b181 390 Apply for the kernel tracer
c9e32613 391\-u, \-\-userspace
6991b181
DG
392 Apply for the user-space tracer
393.fi
394
c9e32613 395.IP "\fBlist\fP [\-k|\-u] [SESSION [SESSION_OPTIONS]]"
6991b181 396.nf
c9e32613 397List tracing session information.
6991b181
DG
398
399With no arguments, it will list available tracing session(s).
400
fa072eae
YB
401With the session name, it will display the details of the session including
402the trace file path, the associated channels and their state (activated
d829b38c 403and deactivated), the activated events and more.
fa072eae 404
c9e32613 405With \-k alone, it will list all available kernel events (except the system
6991b181 406calls events).
c9e32613
DG
407With \-u alone, it will list all available user-space events from registered
408applications. Here is an example of 'lttng list \-u':
6991b181
DG
409
410PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello
411 ust_tests_hello:tptest_sighandler (type: tracepoint)
412 ust_tests_hello:tptest (type: tracepoint)
413
414You can now enable any event listed by using the name :
415\fBust_tests_hello:tptest\fP.
416.fi
417
418.B OPTIONS:
419
420.nf
c9e32613 421\-h, \-\-help
6991b181 422 Show summary of possible options and commands.
c9e32613 423\-\-list-options
6991b181 424 Simple listing of options
c9e32613 425\-k, \-\-kernel
d829b38c 426 Select kernel domain
c9e32613 427\-u, \-\-userspace
6991b181
DG
428 Select user-space domain.
429
430Session options:
c9e32613 431\-c, \-\-channel NAME
6991b181 432 List details of a channel
c9e32613 433\-d, \-\-domain
6991b181
DG
434 List available domain(s)
435.fi
436
437.IP "\fBset-session\fP NAME"
438.nf
439Set current session name
440
441Will change the session name in the .lttngrc file.
442.fi
443
444.B OPTIONS:
445
446.nf
c9e32613 447\-h, \-\-help
6991b181 448 Show summary of possible options and commands.
c9e32613 449\-\-list-options
6991b181
DG
450 Simple listing of options
451.fi
452
453.IP
454
455.IP "\fBstart\fP [OPTIONS] [NAME]"
456.nf
457Start tracing
458
459It will start tracing for all tracers for a specific tracing session.
460
461If NAME is omitted, the session name is taken from the .lttngrc file.
462.fi
463
464.B OPTIONS:
465
466.nf
c9e32613 467\-h, \-\-help
6991b181 468 Show summary of possible options and commands.
c9e32613 469\-\-list-options
6991b181
DG
470 Simple listing of options
471.fi
472
473.IP
474
475.IP "\fBstop\fP [OPTIONS] [NAME]"
476.nf
477Stop tracing
478
479It will stop tracing for all tracers for a specific tracing session.
480
481If NAME is omitted, the session name is taken from the .lttngrc file.
482.fi
483
484.B OPTIONS:
485
486.nf
c9e32613 487\-h, \-\-help
6991b181 488 Show summary of possible options and commands.
c9e32613 489\-\-list-options
6991b181
DG
490 Simple listing of options
491.fi
492
493.IP
494
495.IP "\fBversion\fP"
496.nf
497Show version information
498.fi
499
500.B OPTIONS:
501
502.nf
c9e32613 503\-h, \-\-help
6991b181 504 Show summary of possible options and commands.
c9e32613 505\-\-list-options
6991b181
DG
506 Simple listing of options
507.fi
508
509.IP
510
511.IP "\fBview\fP [SESSION_NAME] [OPTIONS]"
512.nf
513View traces of a tracing session
514
515By default, the babeltrace viewer will be used for text viewing.
516
fa072eae
YB
517If SESSION_NAME is omitted, the session name is taken from the .lttngrc file.
518
6991b181
DG
519.fi
520
521.B OPTIONS:
522
523.nf
c9e32613 524\-h, \-\-help
6991b181 525 Show this help
c9e32613 526\-\-list-options
6991b181 527 Simple listing of options
c9e32613 528\-t, \-\-trace-path PATH
6991b181 529 Trace directory path for the viewer
c9e32613 530\-e, \-\-viewer CMD
6991b181
DG
531 Specify viewer and/or options to use
532 This will completely override the default viewers so
533 please make sure to specify the full command. The trace
534 directory path of the session will be appended at the end
535 to the arguments
536.fi
537
c206d957
DG
538.SH "EXIT VALUES"
539
540.IP "0"
541Success
542
543.IP "1"
544Command error
545
546.IP "2"
547Undefined command
548
549.IP "3"
550Fatal error
551
552.IP "4"
553Command warning
554
555.IP "16"
556No session found by the name given
557
558.IP "18"
559Error in session creation
560
561.IP "21"
562Error in application(s) listing
563
564.IP "28"
565Session name already exists
566
567.IP "33"
568Kernel tracer unavailable
569
570.IP "35"
571Kernel event exists
572
573.IP "37"
574Kernel channel exists
575
576.IP "38"
577Kernel channel creation failed
578
579.IP "39"
580Kernel channel not found
581
582.IP "40"
583Kernel channel disable failed
584
585.IP "41"
586Kernel channel enable failed
587
588.IP "42"
589Kernel context failed
590
591.IP "43"
592Kernel enable event failed
593
594.IP "44"
595Kernel disable event failed
596
597.IP "53"
598Kernel listing events failed
599
600.IP "60"
601UST channel disable failed
602
603.IP "61"
604UST channel enable failed
605
606.IP "62"
607UST adding context failed
608
609.IP "63"
610UST event enable failed
611
612.IP "64"
613UST event disable failed
614
615.IP "66"
616UST start failed
617
618.IP "67"
619UST stop failed
620
621.IP "75"
622UST event exists
623
624.IP "76"
625UST event not found
626
627.IP "77"
628UST context exists
629
630.IP "78"
631UST invalid context
632
633.IP "79"
634Tracing the kernel requires a root lttng-sessiond daemon and "tracing" group
635user membership.
636
637.IP "80"
638Tracing already started
639
640.IP "81"
641Tracing already stopped
642.PP
6991b181
DG
643.SH "ENVIRONMENT VARIABLES"
644
645.PP
646Note that all command line options override environment variables.
647.PP
648
649.PP
05833633 650.IP "LTTNG_SESSIOND_PATH"
c9e32613
DG
651Allows one to specify the full session daemon binary path to lttng command line
652tool. You can also use \-\-sessiond-path option having the same effect.
6991b181
DG
653.SH "SEE ALSO"
654
655.PP
656babeltrace(1), lttng-ust(3), lttng-sessiond(8)
657.PP
658.SH "BUGS"
659
660.PP
fa072eae 661No show stopper bugs are known yet in this version.
6991b181
DG
662
663If you encounter any issues or usability problem, please report it on our
664mailing list <lttng-dev@lists.lttng.org> to help improve this project.
665.SH "CREDITS"
666
667.PP
c9e32613 668lttng is distributed under the GNU General Public License version 2. See the file
6991b181
DG
669COPYING for details.
670.PP
671A Web site is available at http://lttng.org for more information on the LTTng
672project.
673.PP
674You can also find our git tree at http://git.lttng.org.
675.PP
676Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
677.PP
678You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
679.PP
680.SH "THANKS"
681
682.PP
683Thanks to Yannick Brosseau without whom this project would never have been so
684lean and mean! Also thanks to the Ericsson teams working on tracing which
fa072eae 685helped us greatly with detailed bug reports and unusual test cases.
6991b181
DG
686
687Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
688maintainer) and Jon Bernard for our Debian packages.
689
690Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
691Montreal for the LTTng journey.
c9e32613 692.PP
6991b181
DG
693.SH "AUTHORS"
694
695.PP
696lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
697David Goulet. More people have since contributed to it. It is currently
698maintained by David Goulet <dgoulet@efficios.com>.
699.PP
This page took 0.083442 seconds and 4 git commands to generate.