Add lttng_health_check(3) man page
[lttng-tools.git] / doc / man / lttng.1
CommitLineData
9bd578f5 1.TH "LTTNG" "1" "July 17, 2012" "" ""
6991b181
DG
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.
9bd578f5 343
919e300c
MD
344\-\-filter 'expression'
345 Set a filter on a newly enabled event.
9bd578f5
MD
346 Filter expression on event fields, event recording
347 depends on evaluation. Only specify on first activation
348 of a given event within a session. Filter only allowed
349 when enabling events within a session before tracing is
350 started. If the filter fails to link with the event
351 within the traced domain, the event will be discarded.
352 Currently, filter is only implemented for the user-space
353 tracer.
354 Expression examples:
355
356 'intfield > 500 && intfield < 503'
357 '(stringfield == "test" || intfield != 10) && intfield > 33'
358 'doublefield > 1.1 && intfield < 5.3'
359
360 Wildcards are allowed at the end of strings:
361 'seqfield1 == "te*"'
362 In string literals, the escape character is a '\\'.
363 Use '\\*' for the '*' character, and '\\\\' for the
364 '\\' character.
365
6991b181
DG
366.fi
367
c9e32613 368.IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
6991b181
DG
369.nf
370Disable tracing channel
371
372Disabling a channel makes all event(s) in that channel to stop tracing. You can
373enable it back by calling \fBlttng enable-channel NAME\fP again.
374
c9e32613 375If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
376file.
377.fi
378
379.B OPTIONS:
380
381.nf
c9e32613 382\-h, \-\-help
6991b181 383 Show summary of possible options and commands.
c9e32613 384\-\-list-options
6991b181 385 Simple listing of options
c9e32613 386\-s, \-\-session
6991b181 387 Apply on session name
c9e32613 388\-k, \-\-kernel
6991b181 389 Apply for the kernel tracer
c9e32613 390\-u, \-\-userspace
6991b181
DG
391 Apply for the user-space tracer
392.fi
393
c9e32613 394.IP "\fBdisable-event\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
6991b181
DG
395.nf
396Disable tracing event
397
398The event, once disabled, can be re-enabled by calling \fBlttng enable-event
399NAME\fP again.
400
c9e32613 401If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
402file.
403.fi
404
405.B OPTIONS:
406
407.nf
c9e32613 408\-h, \-\-help
6991b181 409 Show summary of possible options and commands.
c9e32613 410\-\-list-options
6991b181 411 Simple listing of options
c9e32613 412\-s, \-\-session
6991b181 413 Apply on session name
c9e32613 414\-k, \-\-kernel
6991b181 415 Apply for the kernel tracer
c9e32613 416\-u, \-\-userspace
6991b181
DG
417 Apply for the user-space tracer
418.fi
419
c9e32613 420.IP "\fBlist\fP [\-k|\-u] [SESSION [SESSION_OPTIONS]]"
6991b181 421.nf
c9e32613 422List tracing session information.
6991b181
DG
423
424With no arguments, it will list available tracing session(s).
425
fa072eae
YB
426With the session name, it will display the details of the session including
427the trace file path, the associated channels and their state (activated
d829b38c 428and deactivated), the activated events and more.
fa072eae 429
c9e32613 430With \-k alone, it will list all available kernel events (except the system
6991b181 431calls events).
c9e32613
DG
432With \-u alone, it will list all available user-space events from registered
433applications. Here is an example of 'lttng list \-u':
6991b181
DG
434
435PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello
436 ust_tests_hello:tptest_sighandler (type: tracepoint)
437 ust_tests_hello:tptest (type: tracepoint)
438
439You can now enable any event listed by using the name :
440\fBust_tests_hello:tptest\fP.
441.fi
442
443.B OPTIONS:
444
445.nf
c9e32613 446\-h, \-\-help
6991b181 447 Show summary of possible options and commands.
c9e32613 448\-\-list-options
6991b181 449 Simple listing of options
c9e32613 450\-k, \-\-kernel
d829b38c 451 Select kernel domain
c9e32613 452\-u, \-\-userspace
6991b181
DG
453 Select user-space domain.
454
455Session options:
c9e32613 456\-c, \-\-channel NAME
6991b181 457 List details of a channel
c9e32613 458\-d, \-\-domain
6991b181
DG
459 List available domain(s)
460.fi
461
462.IP "\fBset-session\fP NAME"
463.nf
464Set current session name
465
466Will change the session name in the .lttngrc file.
467.fi
468
469.B OPTIONS:
470
471.nf
c9e32613 472\-h, \-\-help
6991b181 473 Show summary of possible options and commands.
c9e32613 474\-\-list-options
6991b181
DG
475 Simple listing of options
476.fi
477
478.IP
479
480.IP "\fBstart\fP [OPTIONS] [NAME]"
481.nf
482Start tracing
483
484It will start tracing for all tracers for a specific tracing session.
485
486If NAME is omitted, the session name is taken from the .lttngrc file.
487.fi
488
489.B OPTIONS:
490
491.nf
c9e32613 492\-h, \-\-help
6991b181 493 Show summary of possible options and commands.
c9e32613 494\-\-list-options
6991b181
DG
495 Simple listing of options
496.fi
497
498.IP
499
500.IP "\fBstop\fP [OPTIONS] [NAME]"
501.nf
502Stop tracing
503
504It will stop tracing for all tracers for a specific tracing session.
505
506If NAME is omitted, the session name is taken from the .lttngrc file.
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 "\fBversion\fP"
521.nf
522Show version information
523.fi
524
525.B OPTIONS:
526
527.nf
c9e32613 528\-h, \-\-help
6991b181 529 Show summary of possible options and commands.
c9e32613 530\-\-list-options
6991b181
DG
531 Simple listing of options
532.fi
533
534.IP
535
536.IP "\fBview\fP [SESSION_NAME] [OPTIONS]"
537.nf
538View traces of a tracing session
539
540By default, the babeltrace viewer will be used for text viewing.
541
fa072eae
YB
542If SESSION_NAME is omitted, the session name is taken from the .lttngrc file.
543
6991b181
DG
544.fi
545
546.B OPTIONS:
547
548.nf
c9e32613 549\-h, \-\-help
6991b181 550 Show this help
c9e32613 551\-\-list-options
6991b181 552 Simple listing of options
c9e32613 553\-t, \-\-trace-path PATH
6991b181 554 Trace directory path for the viewer
c9e32613 555\-e, \-\-viewer CMD
6991b181
DG
556 Specify viewer and/or options to use
557 This will completely override the default viewers so
558 please make sure to specify the full command. The trace
559 directory path of the session will be appended at the end
560 to the arguments
561.fi
562
c206d957
DG
563.SH "EXIT VALUES"
564
565.IP "0"
566Success
567
568.IP "1"
569Command error
570
571.IP "2"
572Undefined command
573
574.IP "3"
575Fatal error
576
577.IP "4"
578Command warning
579
580.IP "16"
581No session found by the name given
582
583.IP "18"
584Error in session creation
585
586.IP "21"
587Error in application(s) listing
588
589.IP "28"
590Session name already exists
591
592.IP "33"
593Kernel tracer unavailable
594
595.IP "35"
596Kernel event exists
597
598.IP "37"
599Kernel channel exists
600
601.IP "38"
602Kernel channel creation failed
603
604.IP "39"
605Kernel channel not found
606
607.IP "40"
608Kernel channel disable failed
609
610.IP "41"
611Kernel channel enable failed
612
613.IP "42"
614Kernel context failed
615
616.IP "43"
617Kernel enable event failed
618
619.IP "44"
620Kernel disable event failed
621
622.IP "53"
623Kernel listing events failed
624
625.IP "60"
626UST channel disable failed
627
628.IP "61"
629UST channel enable failed
630
631.IP "62"
632UST adding context failed
633
634.IP "63"
635UST event enable failed
636
637.IP "64"
638UST event disable failed
639
640.IP "66"
641UST start failed
642
643.IP "67"
644UST stop failed
645
646.IP "75"
647UST event exists
648
649.IP "76"
650UST event not found
651
652.IP "77"
653UST context exists
654
655.IP "78"
656UST invalid context
657
658.IP "79"
659Tracing the kernel requires a root lttng-sessiond daemon and "tracing" group
660user membership.
661
662.IP "80"
663Tracing already started
664
665.IP "81"
666Tracing already stopped
5c827ce0
DG
667
668.IP "98"
669No UST consumer detected
670
671.IP "99"
672No Kernel consumer detected
a027b2d2
MD
673
674.IP "100"
675Event already enabled with different loglevel
c206d957 676.PP
6991b181
DG
677.SH "ENVIRONMENT VARIABLES"
678
679.PP
680Note that all command line options override environment variables.
681.PP
682
683.PP
05833633 684.IP "LTTNG_SESSIOND_PATH"
c9e32613
DG
685Allows one to specify the full session daemon binary path to lttng command line
686tool. You can also use \-\-sessiond-path option having the same effect.
6991b181
DG
687.SH "SEE ALSO"
688
689.PP
690babeltrace(1), lttng-ust(3), lttng-sessiond(8)
691.PP
692.SH "BUGS"
693
694.PP
fa072eae 695No show stopper bugs are known yet in this version.
6991b181
DG
696
697If you encounter any issues or usability problem, please report it on our
698mailing list <lttng-dev@lists.lttng.org> to help improve this project.
699.SH "CREDITS"
700
701.PP
c9e32613 702lttng is distributed under the GNU General Public License version 2. See the file
6991b181
DG
703COPYING for details.
704.PP
705A Web site is available at http://lttng.org for more information on the LTTng
706project.
707.PP
708You can also find our git tree at http://git.lttng.org.
709.PP
710Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
711.PP
712You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
713.PP
714.SH "THANKS"
715
716.PP
717Thanks to Yannick Brosseau without whom this project would never have been so
718lean and mean! Also thanks to the Ericsson teams working on tracing which
fa072eae 719helped us greatly with detailed bug reports and unusual test cases.
6991b181
DG
720
721Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
722maintainer) and Jon Bernard for our Debian packages.
723
724Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
725Montreal for the LTTng journey.
c9e32613 726.PP
6991b181
DG
727.SH "AUTHORS"
728
729.PP
730lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
731David Goulet. More people have since contributed to it. It is currently
732maintained by David Goulet <dgoulet@efficios.com>.
733.PP
This page took 0.053436 seconds and 4 git commands to generate.