Fix: filter: remove dependency on UST bug.h
[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.
a3c5b534
FG
242\-a, \-\-all
243 Destroy all sessions
c9e32613 244\-\-list-options
6991b181
DG
245 Simple listing of options
246.fi
247
248.IP
249
250.IP "\fBenable-channel\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
251.nf
252Enable tracing channel
253
b883c01b
DG
254To enable event, you must first enable a channel which contains event(s).
255
c9e32613 256If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
257file.
258.fi
259
260.B OPTIONS:
261
262.nf
c9e32613 263\-h, \-\-help
6991b181 264 Show this help
c9e32613 265\-\-list-options
6991b181 266 Simple listing of options
c9e32613 267\-s, \-\-session
6991b181 268 Apply on session name
c9e32613 269\-k, \-\-kernel
6991b181 270 Apply to the kernel tracer
c9e32613 271\-u, \-\-userspace
6991b181
DG
272 Apply to the user-space tracer
273
c9e32613 274\-\-discard
6991b181 275 Discard event when subbuffers are full (default)
c9e32613 276\-\-overwrite
6991b181 277 Flight recorder mode : overwrites events when subbuffers are full
c9e32613 278\-\-subbuf-size
6991b181 279 Subbuffer size in bytes (default: 4096, kernel default: 262144)
c9e32613 280\-\-num-subbuf
d829b38c 281 Number of subbuffers (default: 4)
93e6c8a0 282 Needs to be a power of 2 for kernel and ust tracers
c9e32613 283\-\-switch-timer
6991b181 284 Switch subbuffer timer interval in usec (default: 0)
93e6c8a0 285 Needs to be a power of 2 for kernel and ust tracers
c9e32613 286\-\-read-timer
6991b181
DG
287 Read timer interval in usec (default: 200)
288.fi
289
290.IP
291
292.IP "\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
293.nf
294Enable tracing event
295
c9e32613 296A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is
6991b181 297omitted, a default channel named '\fBchannel0\fP' is created and the event is
c9e32613 298added to it. For the user-space tracer, using \fB\-a, \-\-all\fP is the same as
6991b181
DG
299using the wildcard "*".
300
c9e32613 301If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
302file.
303.fi
304
305.B OPTIONS:
306
307.nf
c9e32613 308\-h, \-\-help
6991b181 309 Show summary of possible options and commands.
c9e32613 310\-\-list-options
6991b181 311 Simple listing of options
c9e32613 312\-s, \-\-session
6991b181 313 Apply on session name
c9e32613 314\-c, \-\-channel
6991b181 315 Apply on channel name
c9e32613 316\-a, \-\-all
e08bff8d 317 Enable all tracepoints and syscalls
c9e32613 318\-k, \-\-kernel
6991b181 319 Apply for the kernel tracer
c9e32613 320\-u, \-\-userspace
6991b181
DG
321 Apply for the user-space tracer
322
c9e32613 323\-\-tracepoint
6991b181
DG
324 Tracepoint event (default)
325 - userspace tracer supports wildcards at end of string. Don't forget to
326 quote to deal with bash expansion.
327 e.g.:
328 "*"
329 "app_component:na*"
c9e32613 330\-\-loglevel
6991b181 331 Tracepoint loglevel
c9e32613 332\-\-probe [addr | symbol | symbol+offset]
6991b181
DG
333 Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...)
334 or hexadecimal (0xNNN...)
c9e32613 335\-\-function [addr | symbol | symbol+offset]
6991b181
DG
336 Dynamic function entry/return probe. Addr and offset can be octal
337 (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...)
c9e32613 338\-\-syscall
6991b181
DG
339 System call event
340 Enabling syscalls tracing (kernel tracer), you will not be able to disable them
341 with disable-event. This is a known limitation. You can disable the entire
342 channel to do the trick.
919e300c
MD
343\-\-filter 'expression'
344 Set a filter on a newly enabled event.
345 Filter expression on event fields event recording
346 depends on evaluation. Only specify on first activation
347 of a given event within a session. Filter only allowed
348 when enabling events within a session before tracing is
349 started.
6991b181
DG
350.fi
351
c9e32613 352.IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
6991b181
DG
353.nf
354Disable tracing channel
355
356Disabling a channel makes all event(s) in that channel to stop tracing. You can
357enable it back by calling \fBlttng enable-channel NAME\fP again.
358
c9e32613 359If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
360file.
361.fi
362
363.B OPTIONS:
364
365.nf
c9e32613 366\-h, \-\-help
6991b181 367 Show summary of possible options and commands.
c9e32613 368\-\-list-options
6991b181 369 Simple listing of options
c9e32613 370\-s, \-\-session
6991b181 371 Apply on session name
c9e32613 372\-k, \-\-kernel
6991b181 373 Apply for the kernel tracer
c9e32613 374\-u, \-\-userspace
6991b181
DG
375 Apply for the user-space tracer
376.fi
377
c9e32613 378.IP "\fBdisable-event\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
6991b181
DG
379.nf
380Disable tracing event
381
382The event, once disabled, can be re-enabled by calling \fBlttng enable-event
383NAME\fP again.
384
c9e32613 385If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
386file.
387.fi
388
389.B OPTIONS:
390
391.nf
c9e32613 392\-h, \-\-help
6991b181 393 Show summary of possible options and commands.
c9e32613 394\-\-list-options
6991b181 395 Simple listing of options
c9e32613 396\-s, \-\-session
6991b181 397 Apply on session name
c9e32613 398\-k, \-\-kernel
6991b181 399 Apply for the kernel tracer
c9e32613 400\-u, \-\-userspace
6991b181
DG
401 Apply for the user-space tracer
402.fi
403
c9e32613 404.IP "\fBlist\fP [\-k|\-u] [SESSION [SESSION_OPTIONS]]"
6991b181 405.nf
c9e32613 406List tracing session information.
6991b181
DG
407
408With no arguments, it will list available tracing session(s).
409
fa072eae
YB
410With the session name, it will display the details of the session including
411the trace file path, the associated channels and their state (activated
d829b38c 412and deactivated), the activated events and more.
fa072eae 413
c9e32613 414With \-k alone, it will list all available kernel events (except the system
6991b181 415calls events).
c9e32613
DG
416With \-u alone, it will list all available user-space events from registered
417applications. Here is an example of 'lttng list \-u':
6991b181
DG
418
419PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello
420 ust_tests_hello:tptest_sighandler (type: tracepoint)
421 ust_tests_hello:tptest (type: tracepoint)
422
423You can now enable any event listed by using the name :
424\fBust_tests_hello:tptest\fP.
425.fi
426
427.B OPTIONS:
428
429.nf
c9e32613 430\-h, \-\-help
6991b181 431 Show summary of possible options and commands.
c9e32613 432\-\-list-options
6991b181 433 Simple listing of options
c9e32613 434\-k, \-\-kernel
d829b38c 435 Select kernel domain
c9e32613 436\-u, \-\-userspace
6991b181
DG
437 Select user-space domain.
438
439Session options:
c9e32613 440\-c, \-\-channel NAME
6991b181 441 List details of a channel
c9e32613 442\-d, \-\-domain
6991b181
DG
443 List available domain(s)
444.fi
445
446.IP "\fBset-session\fP NAME"
447.nf
448Set current session name
449
450Will change the session name in the .lttngrc file.
451.fi
452
453.B OPTIONS:
454
455.nf
c9e32613 456\-h, \-\-help
6991b181 457 Show summary of possible options and commands.
c9e32613 458\-\-list-options
6991b181
DG
459 Simple listing of options
460.fi
461
462.IP
463
464.IP "\fBstart\fP [OPTIONS] [NAME]"
465.nf
466Start tracing
467
468It will start tracing for all tracers for a specific tracing session.
469
470If NAME is omitted, the session name is taken from the .lttngrc file.
471.fi
472
473.B OPTIONS:
474
475.nf
c9e32613 476\-h, \-\-help
6991b181 477 Show summary of possible options and commands.
c9e32613 478\-\-list-options
6991b181
DG
479 Simple listing of options
480.fi
481
482.IP
483
484.IP "\fBstop\fP [OPTIONS] [NAME]"
485.nf
486Stop tracing
487
488It will stop tracing for all tracers for a specific tracing session.
489
490If NAME is omitted, the session name is taken from the .lttngrc file.
491.fi
492
493.B OPTIONS:
494
495.nf
c9e32613 496\-h, \-\-help
6991b181 497 Show summary of possible options and commands.
c9e32613 498\-\-list-options
6991b181
DG
499 Simple listing of options
500.fi
501
502.IP
503
504.IP "\fBversion\fP"
505.nf
506Show version information
507.fi
508
509.B OPTIONS:
510
511.nf
c9e32613 512\-h, \-\-help
6991b181 513 Show summary of possible options and commands.
c9e32613 514\-\-list-options
6991b181
DG
515 Simple listing of options
516.fi
517
518.IP
519
520.IP "\fBview\fP [SESSION_NAME] [OPTIONS]"
521.nf
522View traces of a tracing session
523
524By default, the babeltrace viewer will be used for text viewing.
525
fa072eae
YB
526If SESSION_NAME is omitted, the session name is taken from the .lttngrc file.
527
6991b181
DG
528.fi
529
530.B OPTIONS:
531
532.nf
c9e32613 533\-h, \-\-help
6991b181 534 Show this help
c9e32613 535\-\-list-options
6991b181 536 Simple listing of options
c9e32613 537\-t, \-\-trace-path PATH
6991b181 538 Trace directory path for the viewer
c9e32613 539\-e, \-\-viewer CMD
6991b181
DG
540 Specify viewer and/or options to use
541 This will completely override the default viewers so
542 please make sure to specify the full command. The trace
543 directory path of the session will be appended at the end
544 to the arguments
545.fi
546
c206d957
DG
547.SH "EXIT VALUES"
548
549.IP "0"
550Success
551
552.IP "1"
553Command error
554
555.IP "2"
556Undefined command
557
558.IP "3"
559Fatal error
560
561.IP "4"
562Command warning
563
564.IP "16"
565No session found by the name given
566
567.IP "18"
568Error in session creation
569
570.IP "21"
571Error in application(s) listing
572
573.IP "28"
574Session name already exists
575
576.IP "33"
577Kernel tracer unavailable
578
579.IP "35"
580Kernel event exists
581
582.IP "37"
583Kernel channel exists
584
585.IP "38"
586Kernel channel creation failed
587
588.IP "39"
589Kernel channel not found
590
591.IP "40"
592Kernel channel disable failed
593
594.IP "41"
595Kernel channel enable failed
596
597.IP "42"
598Kernel context failed
599
600.IP "43"
601Kernel enable event failed
602
603.IP "44"
604Kernel disable event failed
605
606.IP "53"
607Kernel listing events failed
608
609.IP "60"
610UST channel disable failed
611
612.IP "61"
613UST channel enable failed
614
615.IP "62"
616UST adding context failed
617
618.IP "63"
619UST event enable failed
620
621.IP "64"
622UST event disable failed
623
624.IP "66"
625UST start failed
626
627.IP "67"
628UST stop failed
629
630.IP "75"
631UST event exists
632
633.IP "76"
634UST event not found
635
636.IP "77"
637UST context exists
638
639.IP "78"
640UST invalid context
641
642.IP "79"
643Tracing the kernel requires a root lttng-sessiond daemon and "tracing" group
644user membership.
645
646.IP "80"
647Tracing already started
648
649.IP "81"
650Tracing already stopped
5c827ce0
DG
651
652.IP "98"
653No UST consumer detected
654
655.IP "99"
656No Kernel consumer detected
a027b2d2
MD
657
658.IP "100"
659Event already enabled with different loglevel
c206d957 660.PP
6991b181
DG
661.SH "ENVIRONMENT VARIABLES"
662
663.PP
664Note that all command line options override environment variables.
665.PP
666
667.PP
05833633 668.IP "LTTNG_SESSIOND_PATH"
c9e32613
DG
669Allows one to specify the full session daemon binary path to lttng command line
670tool. You can also use \-\-sessiond-path option having the same effect.
6991b181
DG
671.SH "SEE ALSO"
672
673.PP
674babeltrace(1), lttng-ust(3), lttng-sessiond(8)
675.PP
676.SH "BUGS"
677
678.PP
fa072eae 679No show stopper bugs are known yet in this version.
6991b181
DG
680
681If you encounter any issues or usability problem, please report it on our
682mailing list <lttng-dev@lists.lttng.org> to help improve this project.
683.SH "CREDITS"
684
685.PP
c9e32613 686lttng is distributed under the GNU General Public License version 2. See the file
6991b181
DG
687COPYING for details.
688.PP
689A Web site is available at http://lttng.org for more information on the LTTng
690project.
691.PP
692You can also find our git tree at http://git.lttng.org.
693.PP
694Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
695.PP
696You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
697.PP
698.SH "THANKS"
699
700.PP
701Thanks to Yannick Brosseau without whom this project would never have been so
702lean and mean! Also thanks to the Ericsson teams working on tracing which
fa072eae 703helped us greatly with detailed bug reports and unusual test cases.
6991b181
DG
704
705Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
706maintainer) and Jon Bernard for our Debian packages.
707
708Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
709Montreal for the LTTng journey.
c9e32613 710.PP
6991b181
DG
711.SH "AUTHORS"
712
713.PP
714lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
715David Goulet. More people have since contributed to it. It is currently
716maintained by David Goulet <dgoulet@efficios.com>.
717.PP
This page took 0.085171 seconds and 4 git commands to generate.