Merge branch 'master' of git://git.lttng.org/lttng-tools
[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
20The \fBlttng\fP command line tool from lttng-tools package is used to control
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
35running as Alice that can be use to trace her applications along side with a
36root daemon or even a Bob daemon. We highly recommand to start the session
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.
c9e32613 56FIXME : details (\-v : sessiond verbose, \-vv : consumerd verbose, etc) ?
6991b181 57.TP
c9e32613 58.BR "\-q, \-\-quiet"
6991b181
DG
59Suppress all messages (even errors).
60.TP
c9e32613 61.BR "\-g, \-\-group NAME"
6991b181
DG
62Set unix tracing group name. (default: tracing)
63.TP
c9e32613 64.BR "\-n, \-\-no-sessiond"
6991b181
DG
65Don't automatically spawn a session daemon.
66.TP
c9e32613 67.BR "\-\-sessiond\-path"
6991b181
DG
68Set session daemon full binary path.
69.TP
c9e32613 70.BR "\-\-list\-options"
6991b181
DG
71Simple listing of lttng options.
72.TP
c9e32613 73.BR "\-\-list\-commands"
6991b181
DG
74Simple listing of lttng commands.
75.SH "COMMANDS"
76
77.TP
78\fBadd-context\fP
79.nf
80Add context to event(s) and/or channel(s).
81
82A context is basically extra information appended to a channel or event. For
83instance, you could ask the tracer to add the PID information within the
84"sched_switch" kernel event. You can also add performance monitoring unit
85counters (perf PMU) using the perf kernel API).
86
87For example, this command will add the context information 'prio' and two perf
88counters (hardware branch misses and cache misses), to all events in the trace
89data output:
90
c9e32613 91# lttng add-context \-k \-t prio \-t perf:branch-misses \-t perf:cache-misses
6991b181 92
c9e32613 93Please take a look at the help (\-h/\-\-help) for a detailed list of available
6991b181
DG
94contexts.
95
c9e32613 96If no channel and no event is given (\-c/\-e), the context is added to all
6991b181 97channels (which applies automatically to all events in that channel). Otherwise
c9e32613 98the context will be added only to the channel (\-c) and/or event (\-e) indicated.
6991b181 99
c9e32613 100If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
101file.
102.fi
103
104.B OPTIONS:
105
106.nf
c9e32613 107\-h, \-\-help
6991b181 108 Show summary of possible options and commands.
c9e32613 109\-s, \-\-session NAME
6991b181 110 Apply on session name.
c9e32613 111\-c, \-\-channel NAME
6991b181 112 Apply on channel name.
c9e32613 113\-e, \-\-event NAME
6991b181 114 Apply on event name.
c9e32613 115\-k, \-\-kernel
6991b181 116 Apply for the kernel tracer
c9e32613 117\-u, \-\-userspace
6991b181 118 Apply for the user-space tracer
c9e32613 119\-t, \-\-type TYPE
6991b181 120 Context type. You can repeat this option on the command line. Please
c9e32613 121 use "lttng add-context \-h" to list all available types.
6991b181
DG
122.fi
123
124.IP
125
126.IP "\fBcalibrate\fP"
127.nf
128Quantify LTTng overhead
129
130The LTTng calibrate command can be used to find out the combined average
131overhead of the LTTng tracer and the instrumentation mechanisms used. This
132overhead can be calibrated in terms of time or using any of the PMU performance
133counter available on the system.
134
135For now, the only calibration implemented is that of the kernel function
136instrumentation (kretprobes).
137
138* Calibrate kernel function instrumentation
139
140Let's use an example to show this calibration. We use an i7 processor with 4
141general-purpose PMU registers. This information is available by issuing dmesg,
142looking for "generic registers".
143
144This sequence of commands will gather a trace executing a kretprobe hooked on
145an empty function, gathering PMU counters LLC (Last Level Cache) misses
c9e32613 146information (see lttng add-context \-\-help to see the list of available PMU
6991b181
DG
147counters).
148
149# lttng create calibrate-function
c9e32613
DG
150# lttng enable-event calibrate \-\-kernel \-\-function lttng_calibrate_kretprobe
151# lttng add-context \-\-kernel \-t perf:LLC-load-misses \-t perf:LLC-store-misses \\
152 \-t perf:LLC-prefetch-misses
6991b181
DG
153# lttng start
154# for a in $(seq 1 10); do \\
c9e32613 155 lttng calibrate \-\-kernel \-\-function;
6991b181
DG
156 done
157# lttng destroy
c9e32613 158# babeltrace $(ls \-1drt ~/lttng-traces/calibrate-function-* | tail \-n 1)
6991b181
DG
159
160The output from babeltrace can be saved to a text file and opened in a
161spreadsheet (e.g. oocalc) to focus on the per-PMU counter delta between
162consecutive "calibrate_entry" and "calibrate_return" events. Note that these
163counters are per-CPU, so scheduling events would need to be present to account
164for migration between CPU. Therefore, for calibration purposes, only events
165staying on the same CPU must be considered.
166
167The average result, for the i7, on 10 samples:
168
169 Average Std.Dev.
170perf_LLC_load_misses: 5.0 0.577
171perf_LLC_store_misses: 1.6 0.516
172perf_LLC_prefetch_misses: 9.0 14.742
173
174As we can notice, the load and store misses are relatively stable across runs
175(their standard deviation is relatively low) compared to the prefetch misses.
176We can conclude from this information that LLC load and store misses can be
177accounted for quite precisely, but prefetches within a function seems to behave
178too erratically (not much causality link between the code executed and the CPU
179prefetch activity) to be accounted for.
180.fi
181
182.B OPTIONS:
183
184.nf
c9e32613 185\-h, \-\-help
6991b181 186 Show summary of possible options and commands.
c9e32613 187\-k, \-\-kernel
6991b181 188 Apply for the kernel tracer
c9e32613 189\-u, \-\-userspace
6991b181 190 Apply for the user-space tracer
c9e32613 191\-\-function
6991b181
DG
192 Dynamic function entry/return probe (default)
193.fi
194
195.IP
196
197.IP "\fBcreate\fP [OPTIONS] [NAME]
198.nf
199Create tracing session.
200
201A tracing session contains channel(s) which contains event(s). It is domain
202agnostic meaning that you can enable channels and events for either the
203user-space tracer and/or the kernel tracer. It acts like a container
204aggregating multiple tracing sources.
205
206On creation, a \fB.lttngrc\fP file is created in your $HOME directory
207containing the current session name. If NAME is omitted, a session name is
208automatically created having this form: 'auto-yyyymmdd-hhmms'.
209
c9e32613 210If no \fB\-o, \-\-output\fP is specified, the traces will be written in
6991b181
DG
211$HOME/lttng-traces.
212.fi
213
214.B OPTIONS:
215
216.nf
c9e32613 217\-h, \-\-help
6991b181 218 Show summary of possible options and commands.
c9e32613 219\-\-list-options
6991b181 220 Simple listing of options
c9e32613 221\-o, \-\-output PATH
6991b181
DG
222 Specify output path for traces
223.fi
224
225.IP
226
227.IP "\fBdestroy\fP [OPTIONS] [NAME]"
228.nf
229Teardown tracing session
230
231Free memory on the session daemon and tracer side. It's gone!
232
233If NAME is omitted, the session name is taken from the .lttngrc file.
234.fi
235
236.B OPTIONS:
237
238.nf
c9e32613 239\-h, \-\-help
6991b181 240 Show summary of possible options and commands.
c9e32613 241\-\-list-options
6991b181
DG
242 Simple listing of options
243.fi
244
245.IP
246
247.IP "\fBenable-channel\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
248.nf
249Enable tracing channel
250
c9e32613 251If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
252file.
253.fi
254
255.B OPTIONS:
256
257.nf
c9e32613 258\-h, \-\-help
6991b181 259 Show this help
c9e32613 260\-\-list-options
6991b181 261 Simple listing of options
c9e32613 262\-s, \-\-session
6991b181 263 Apply on session name
c9e32613 264\-k, \-\-kernel
6991b181 265 Apply to the kernel tracer
c9e32613 266\-u, \-\-userspace
6991b181
DG
267 Apply to the user-space tracer
268
c9e32613 269\-\-discard
6991b181 270 Discard event when subbuffers are full (default)
c9e32613 271\-\-overwrite
6991b181 272 Flight recorder mode : overwrites events when subbuffers are full
c9e32613 273\-\-subbuf-size
6991b181 274 Subbuffer size in bytes (default: 4096, kernel default: 262144)
c9e32613 275\-\-num-subbuf
9f778c9a 276 Number of subbufers (default: 4)
93e6c8a0 277 Needs to be a power of 2 for kernel and ust tracers
c9e32613 278\-\-switch-timer
6991b181 279 Switch subbuffer timer interval in usec (default: 0)
93e6c8a0 280 Needs to be a power of 2 for kernel and ust tracers
c9e32613 281\-\-read-timer
6991b181
DG
282 Read timer interval in usec (default: 200)
283.fi
284
285.IP
286
287.IP "\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
288.nf
289Enable tracing event
290
c9e32613 291A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is
6991b181 292omitted, a default channel named '\fBchannel0\fP' is created and the event is
c9e32613 293added to it. For the user-space tracer, using \fB\-a, \-\-all\fP is the same as
6991b181
DG
294using the wildcard "*".
295
c9e32613 296If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
297file.
298.fi
299
300.B OPTIONS:
301
302.nf
c9e32613 303\-h, \-\-help
6991b181 304 Show summary of possible options and commands.
c9e32613 305\-\-list-options
6991b181 306 Simple listing of options
c9e32613 307\-s, \-\-session
6991b181 308 Apply on session name
c9e32613 309\-c, \-\-channel
6991b181 310 Apply on channel name
c9e32613 311\-a, \-\-all
e08bff8d 312 Enable all tracepoints and syscalls
c9e32613 313\-k, \-\-kernel
6991b181 314 Apply for the kernel tracer
c9e32613 315\-u, \-\-userspace
6991b181
DG
316 Apply for the user-space tracer
317
c9e32613 318\-\-tracepoint
6991b181
DG
319 Tracepoint event (default)
320 - userspace tracer supports wildcards at end of string. Don't forget to
321 quote to deal with bash expansion.
322 e.g.:
323 "*"
324 "app_component:na*"
c9e32613 325\-\-loglevel
6991b181 326 Tracepoint loglevel
c9e32613 327\-\-probe [addr | symbol | symbol+offset]
6991b181
DG
328 Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...)
329 or hexadecimal (0xNNN...)
c9e32613 330\-\-function [addr | symbol | symbol+offset]
6991b181
DG
331 Dynamic function entry/return probe. Addr and offset can be octal
332 (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...)
c9e32613 333\-\-syscall
6991b181
DG
334 System call event
335 Enabling syscalls tracing (kernel tracer), you will not be able to disable them
336 with disable-event. This is a known limitation. You can disable the entire
337 channel to do the trick.
338.fi
339
c9e32613 340.IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
6991b181
DG
341.nf
342Disable tracing channel
343
344Disabling a channel makes all event(s) in that channel to stop tracing. You can
345enable it back by calling \fBlttng enable-channel NAME\fP again.
346
c9e32613 347If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
348file.
349.fi
350
351.B OPTIONS:
352
353.nf
c9e32613 354\-h, \-\-help
6991b181 355 Show summary of possible options and commands.
c9e32613 356\-\-list-options
6991b181 357 Simple listing of options
c9e32613 358\-s, \-\-session
6991b181 359 Apply on session name
c9e32613 360\-k, \-\-kernel
6991b181 361 Apply for the kernel tracer
c9e32613 362\-u, \-\-userspace
6991b181
DG
363 Apply for the user-space tracer
364.fi
365
c9e32613 366.IP "\fBdisable-event\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
6991b181
DG
367.nf
368Disable tracing event
369
370The event, once disabled, can be re-enabled by calling \fBlttng enable-event
371NAME\fP again.
372
c9e32613 373If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
374file.
375.fi
376
377.B OPTIONS:
378
379.nf
c9e32613 380\-h, \-\-help
6991b181 381 Show summary of possible options and commands.
c9e32613 382\-\-list-options
6991b181 383 Simple listing of options
c9e32613 384\-s, \-\-session
6991b181 385 Apply on session name
c9e32613 386\-k, \-\-kernel
6991b181 387 Apply for the kernel tracer
c9e32613 388\-u, \-\-userspace
6991b181
DG
389 Apply for the user-space tracer
390.fi
391
c9e32613 392.IP "\fBlist\fP [\-k|\-u] [SESSION [SESSION_OPTIONS]]"
6991b181 393.nf
c9e32613 394List tracing session information.
6991b181
DG
395
396With no arguments, it will list available tracing session(s).
397
c9e32613 398With \-k alone, it will list all available kernel events (except the system
6991b181 399calls events).
c9e32613
DG
400With \-u alone, it will list all available user-space events from registered
401applications. Here is an example of 'lttng list \-u':
6991b181
DG
402
403PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello
404 ust_tests_hello:tptest_sighandler (type: tracepoint)
405 ust_tests_hello:tptest (type: tracepoint)
406
407You can now enable any event listed by using the name :
408\fBust_tests_hello:tptest\fP.
409.fi
410
411.B OPTIONS:
412
413.nf
c9e32613 414\-h, \-\-help
6991b181 415 Show summary of possible options and commands.
c9e32613 416\-\-list-options
6991b181 417 Simple listing of options
c9e32613 418\-k, \-\-kernel
6991b181 419 Select kernel domain (FIXME : apparition de la notion de "domain" ici)
c9e32613 420\-u, \-\-userspace
6991b181
DG
421 Select user-space domain.
422
423Session options:
c9e32613 424\-c, \-\-channel NAME
6991b181 425 List details of a channel
c9e32613 426\-d, \-\-domain
6991b181
DG
427 List available domain(s)
428.fi
429
430.IP "\fBset-session\fP NAME"
431.nf
432Set current session name
433
434Will change the session name in the .lttngrc file.
435.fi
436
437.B OPTIONS:
438
439.nf
c9e32613 440\-h, \-\-help
6991b181 441 Show summary of possible options and commands.
c9e32613 442\-\-list-options
6991b181
DG
443 Simple listing of options
444.fi
445
446.IP
447
448.IP "\fBstart\fP [OPTIONS] [NAME]"
449.nf
450Start tracing
451
452It will start tracing for all tracers for a specific tracing session.
453
454If NAME is omitted, the session name is taken from the .lttngrc file.
455.fi
456
457.B OPTIONS:
458
459.nf
c9e32613 460\-h, \-\-help
6991b181 461 Show summary of possible options and commands.
c9e32613 462\-\-list-options
6991b181
DG
463 Simple listing of options
464.fi
465
466.IP
467
468.IP "\fBstop\fP [OPTIONS] [NAME]"
469.nf
470Stop tracing
471
472It will stop tracing for all tracers for a specific tracing session.
473
474If NAME is omitted, the session name is taken from the .lttngrc file.
475.fi
476
477.B OPTIONS:
478
479.nf
c9e32613 480\-h, \-\-help
6991b181 481 Show summary of possible options and commands.
c9e32613 482\-\-list-options
6991b181
DG
483 Simple listing of options
484.fi
485
486.IP
487
488.IP "\fBversion\fP"
489.nf
490Show version information
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 "\fBview\fP [SESSION_NAME] [OPTIONS]"
505.nf
506View traces of a tracing session
507
508By default, the babeltrace viewer will be used for text viewing.
509
510The SESSION_NAME is an optional session name. If not specified, lttng will get
511it from the configuration file (.lttngrc).
512.fi
513
514.B OPTIONS:
515
516.nf
c9e32613 517\-h, \-\-help
6991b181 518 Show this help
c9e32613 519\-\-list-options
6991b181 520 Simple listing of options
c9e32613 521\-t, \-\-trace-path PATH
6991b181 522 Trace directory path for the viewer
c9e32613 523\-e, \-\-viewer CMD
6991b181
DG
524 Specify viewer and/or options to use
525 This will completely override the default viewers so
526 please make sure to specify the full command. The trace
527 directory path of the session will be appended at the end
528 to the arguments
529.fi
530
531.SH "ENVIRONMENT VARIABLES"
532
533.PP
534Note that all command line options override environment variables.
535.PP
536
537.PP
538.IP "LTTNG_SESSIOND_PATH_ENV"
c9e32613
DG
539Allows one to specify the full session daemon binary path to lttng command line
540tool. You can also use \-\-sessiond-path option having the same effect.
6991b181
DG
541.SH "SEE ALSO"
542
543.PP
544babeltrace(1), lttng-ust(3), lttng-sessiond(8)
545.PP
546.SH "BUGS"
547
548.PP
549No show stopper bugs known yet at this stable version.
550
551If you encounter any issues or usability problem, please report it on our
552mailing list <lttng-dev@lists.lttng.org> to help improve this project.
553.SH "CREDITS"
554
555.PP
c9e32613 556lttng is distributed under the GNU General Public License version 2. See the file
6991b181
DG
557COPYING for details.
558.PP
559A Web site is available at http://lttng.org for more information on the LTTng
560project.
561.PP
562You can also find our git tree at http://git.lttng.org.
563.PP
564Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
565.PP
566You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
567.PP
568.SH "THANKS"
569
570.PP
571Thanks to Yannick Brosseau without whom this project would never have been so
572lean and mean! Also thanks to the Ericsson teams working on tracing which
573helped us greatly with detailled bug reports and unusual test cases.
574
575Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
576maintainer) and Jon Bernard for our Debian packages.
577
578Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
579Montreal for the LTTng journey.
c9e32613 580.PP
6991b181
DG
581.SH "AUTHORS"
582
583.PP
584lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
585David Goulet. More people have since contributed to it. It is currently
586maintained by David Goulet <dgoulet@efficios.com>.
587.PP
This page took 0.076685 seconds and 4 git commands to generate.