doc/man/lttng.1

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