Fix: syntax error in lttng.1
[lttng-tools.git] / doc / man / lttng.1
1 .TH "LTTNG" "1" "February 05th, 2014" "" ""
2
3 .SH "NAME"
4 lttng \(em LTTng 2.x tracer control command line tool
5
6 .SH "SYNOPSIS"
7
8 .PP
9 lttng [OPTIONS] <COMMAND>
10 .SH "DESCRIPTION"
11
12 .PP
13 The LTTng project aims at providing highly efficient tracing tools for Linux.
14 Its tracers help track down performance issues and debug problems
15 involving multiple concurrent processes and threads. Tracing across multiple
16 systems is also possible.
17
18 The \fBlttng\fP command line tool from the lttng-tools package is used to control
19 both kernel and user-space tracing. Every interaction with the tracer should
20 be done by this tool or by the liblttng-ctl library provided by the lttng-tools
21 package.
22
23 LTTng uses a session daemon (lttng-sessiond(8)), acting as a tracing registry,
24 which allows you to interact with multiple tracers (kernel and user-space)
25 inside the same container, a tracing session. Traces can be gathered from the
26 kernel and/or instrumented applications (lttng-ust(3)). Aggregating and reading
27 those traces is done using the babeltrace(1) text viewer.
28
29 We introduce the notion of \fBtracing domains\fP which is essentially a type of
30 tracer (kernel, user space or JUL for now). In the future, we could see more
31 tracer like for instance an hypervisor. For some commands, you'll need to
32 specify on which domain the command operates (\-u, \-k or \-j). For instance,
33 the kernel domain must be specified when enabling a kernel event.
34
35 In order to trace the kernel, the session daemon needs to be running as root.
36 LTTng provides the use of a \fBtracing group\fP (default: tracing). Whomever is
37 in that group can interact with the root session daemon and thus trace the
38 kernel. Session daemons can co-exist, meaning that you can have a session daemon
39 running as Alice that can be used to trace her applications along side with a
40 root daemon or even a Bob daemon. We highly recommend starting the session
41 daemon at boot time for stable and long term tracing.
42
43 Each user-space application instrumented with lttng-ust(3) will automatically
44 register with the root session daemon and its user session daemon. This allows
45 each daemon to list the available traceable applications and tracepoints at any
46 given moment (See the \fBlist\fP command).
47 .SH "OPTIONS"
48
49 .PP
50 This program follow the usual GNU command line syntax with long options starting with
51 two dashes. Below is a summary of the available options.
52 .PP
53
54 .TP
55 .BR "\-h, \-\-help"
56 Show summary of possible options and commands.
57 .TP
58 .BR "\-v, \-\-verbose"
59 Increase verbosity.
60 Three levels of verbosity are available which are triggered by putting additional v to
61 the option (\-vv or \-vvv)
62 .TP
63 .BR "\-q, \-\-quiet"
64 Suppress all messages (even errors).
65 .TP
66 .BR "\-g, \-\-group NAME"
67 Set unix tracing group name. (default: tracing)
68 .TP
69 .BR "\-n, \-\-no-sessiond"
70 Don't automatically spawn a session daemon.
71 .TP
72 .BR "\-\-sessiond\-path PATH"
73 Set session daemon full binary path.
74 .TP
75 .BR "\-\-list\-options"
76 Simple listing of lttng options.
77 .TP
78 .BR "\-\-list\-commands"
79 Simple listing of lttng commands.
80 .SH "COMMANDS"
81
82 .PP
83 \fBadd-context\fP [OPTIONS]
84 .RS
85 Add context to event(s) and/or channel(s).
86
87 A context is basically extra information appended to a channel. For instance,
88 you could ask the tracer to add the PID information for all events in a
89 channel. You can also add performance monitoring unit counters (perf PMU) using
90 the perf kernel API).
91
92 For example, this command will add the context information 'prio' and two perf
93 counters (hardware branch misses and cache misses), to all events in the trace
94 data output:
95
96 .nf
97 # lttng add-context \-k \-t prio \-t perf:branch-misses \\
98 \-t perf:cache-misses
99 .fi
100
101 Please take a look at the help (\-h/\-\-help) for a detailed list of available
102 contexts.
103
104 If no channel is given (\-c), the context is added to all channels that were
105 already enabled. If the session has no channel, a default channel is created.
106 Otherwise the context will be added only to the given channel (\-c).
107
108 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
109 file.
110
111 .B OPTIONS:
112
113 .TP
114 .BR "\-h, \-\-help"
115 Show summary of possible options and commands.
116 .TP
117 .BR "\-s, \-\-session NAME"
118 Apply on session name.
119 .TP
120 .BR "\-c, \-\-channel NAME"
121 Apply on channel name.
122 .TP
123 .BR "\-k, \-\-kernel"
124 Apply for the kernel tracer
125 .TP
126 .BR "\-u, \-\-userspace"
127 Apply for the user-space tracer
128 .TP
129 .BR "\-t, \-\-type TYPE"
130 Context type. You can repeat this option on the command line. Please
131 use "lttng add-context \-h" to list all available types.
132 .RE
133 .PP
134
135 .PP
136 \fBcalibrate\fP [OPTIONS]
137 .RS
138 Quantify LTTng overhead
139
140 The LTTng calibrate command can be used to find out the combined average
141 overhead of the LTTng tracer and the instrumentation mechanisms used. This
142 overhead can be calibrated in terms of time or using any of the PMU performance
143 counter available on the system.
144
145 For now, the only calibration implemented is that of the kernel function
146 instrumentation (kretprobes).
147
148 * Calibrate kernel function instrumentation
149
150 Let's use an example to show this calibration. We use an i7 processor with 4
151 general-purpose PMU registers. This information is available by issuing dmesg,
152 looking for "generic registers".
153
154 This sequence of commands will gather a trace executing a kretprobe hooked on
155 an empty function, gathering PMU counters LLC (Last Level Cache) misses
156 information (see lttng add-context \-\-help to see the list of available PMU
157 counters).
158
159 .nf
160 # lttng create calibrate-function
161 # lttng enable-event calibrate \-\-kernel \\
162 \-\-function lttng_calibrate_kretprobe
163 # lttng add-context \-\-kernel \-t perf:LLC-load-misses \\
164 \-t perf:LLC-store-misses \\
165 \-t perf:LLC-prefetch-misses
166 # lttng start
167 # for a in $(seq 1 10); do \\
168 lttng calibrate \-\-kernel \-\-function;
169 done
170 # lttng destroy
171 # babeltrace $(ls \-1drt ~/lttng-traces/calibrate-function-* \\
172 | tail \-n 1)
173 .fi
174
175 The output from babeltrace can be saved to a text file and opened in a
176 spreadsheet (e.g. oocalc) to focus on the per-PMU counter delta between
177 consecutive "calibrate_entry" and "calibrate_return" events. Note that these
178 counters are per-CPU, so scheduling events would need to be present to account
179 for migration between CPU. Therefore, for calibration purposes, only events
180 staying on the same CPU must be considered.
181
182 The average result, for the i7, on 10 samples:
183
184 .nf
185 Average Std.Dev.
186 perf_LLC_load_misses: 5.0 0.577
187 perf_LLC_store_misses: 1.6 0.516
188 perf_LLC_prefetch_misses: 9.0 14.742
189 .fi
190
191 As we can notice, the load and store misses are relatively stable across runs
192 (their standard deviation is relatively low) compared to the prefetch misses.
193 We can conclude from this information that LLC load and store misses can be
194 accounted for quite precisely, but prefetches within a function seems to behave
195 too erratically (not much causality link between the code executed and the CPU
196 prefetch activity) to be accounted for.
197
198 .B OPTIONS:
199
200 .TP
201 .BR "\-h, \-\-help"
202 Show summary of possible options and commands.
203 .TP
204 .BR "\-k, \-\-kernel"
205 Apply for the kernel tracer
206 .TP
207 .BR "\-u, \-\-userspace"
208 Apply for the user-space tracer
209 .TP
210 .BR "\-\-function"
211 Dynamic function entry/return probe (default)
212 .RE
213 .PP
214
215 .PP
216 \fBcreate\fP [NAME] [OPTIONS]
217 .RS
218 Create tracing session.
219
220 A tracing session contains channel(s) which contains event(s). It is domain
221 agnostic, meaning that channels and events can be enabled for the
222 user-space tracer and/or the kernel tracer. It acts like a container
223 aggregating multiple tracing sources.
224
225 On creation, a \fB.lttngrc\fP file is created in your $HOME directory
226 containing the current session name. If NAME is omitted, a session name is
227 automatically created having this form: 'auto-yyyymmdd-hhmmss'.
228
229 If no \fB\-o, \-\-output\fP is specified, the traces will be written in
230 $HOME/lttng-traces.
231
232 The $HOME environment variable can be overridden by defining the environment
233 variable LTTNG_HOME. This is useful when the user running the commands has
234 a non-writeable home directory.
235
236 The session name MUST NOT contain the character '/'.
237
238 .B OPTIONS:
239
240 .TP
241 .BR "\-h, \-\-help"
242 Show summary of possible options and commands.
243 .TP
244 .BR "\-\-list-options"
245 Simple listing of options
246 .TP
247 .BR "\-o, \-\-output PATH"
248 Specify output path for traces
249 .TP
250 .BR "\-\-no-output"
251 Traces will not be output
252 .TP
253 .BR "\-\-snapshot"
254 Set the session in snapshot mode. Created in no-output mode and uses the
255 URL, if one is specified, as the default snapshot output. Every channel will be set
256 in overwrite mode and with mmap output (splice not supported).
257 .TP
258 .BR "\-\-live [USEC]"
259 Set the session exclusively in live mode. The paremeter is the delay in micro
260 seconds before the data is flushed and streamed. The live mode allows you to
261 stream the trace and view it while it's being recorded by any tracer. For that,
262 you need a lttng-relayd and this session requires a network URL (\-U or
263 \-C/\-D). If no USEC nor URL is provided, the default is to use a timer value
264 set to 1000000 and the network URL set to net://127.0.0.1.
265
266 To read a live session, you can use babeltrace(1) or the live streaming
267 protocol in doc/live-reading-protocol.txt. Here is an example:
268
269 .nf
270 $ lttng-relayd -o /tmp/lttng
271 $ lttng create --live 200000 -U net://localhost
272 $ lttng enable-event -a --userspace
273 $ lttng start
274 .fi
275
276 After the start, you'll be able to read the events while they are being
277 recorded in /tmp/lttng.
278
279 .TP
280 .BR "\-U, \-\-set-url=URL"
281 Set URL for the consumer output destination. It is persistent for the
282 session lifetime. Redo the command to change it. This will set both data
283 and control URL for network.
284 .TP
285 .BR "\-C, \-\-ctrl-url=URL"
286 Set control path URL. (Must use -D also)
287 .TP
288 .BR "\-D, \-\-data-url=URL"
289 Set data path URL. (Must use -C also)
290 .PP
291 Using these options, each API call can be controlled individually. For
292 instance, \-C does not enable the consumer automatically. You'll need the \-e
293 option for that.
294
295 .B URL FORMAT:
296
297 proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH]
298
299 Supported protocols are (proto):
300 .TP
301 .BR "file://..."
302 Local filesystem full path.
303
304 .TP
305 .BR "net://..."
306 This will use the default network transport layer which is TCP for both
307 control (PORT1) and data port (PORT2). The default ports are
308 respectively 5342 and 5343. Note that net[6]:// is not yet supported.
309
310 .TP
311 .BR "tcp[6]://..."
312 Can only be used with -C and -D together
313
314 NOTE: IPv6 address MUST be enclosed in brackets '[]' (rfc2732)
315
316 .B EXAMPLES:
317
318 .nf
319 # lttng create -U net://192.168.1.42
320 .fi
321 Uses TCP and default ports for the given destination.
322
323 .nf
324 # lttng create -U net6://[fe80::f66d:4ff:fe53:d220]
325 .fi
326 Uses TCP, default ports and IPv6.
327
328 .nf
329 # lttng create s1 -U net://myhost.com:3229
330 .fi
331 Create session s1 and set its consumer to myhost.com on port 3229 for control.
332 .RE
333 .PP
334
335 .PP
336 \fBdestroy\fP [NAME] [OPTIONS]
337 .RS
338 Teardown tracing session
339
340 Free memory on the session daemon and tracer side. It's gone!
341
342 If NAME is omitted, the session name is taken from the .lttngrc file.
343
344 .B OPTIONS:
345
346 .TP
347 .BR "\-h, \-\-help"
348 Show summary of possible options and commands.
349 .TP
350 .BR "\-a, \-\-all"
351 Destroy all sessions
352 .TP
353 .BR "\-\-list-options"
354 Simple listing of options
355 .RE
356 .PP
357
358 .PP
359 \fBenable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
360 .RS
361 Enable tracing channel
362
363 To enable an event, you must enable both the event and the channel that
364 contains it.
365
366 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
367 file.
368
369 Exactly one of \-k or -u must be specified.
370
371 It is important to note that if a certain type of buffers is used, the session
372 will be set with that type and all other subsequent channel needs to have the
373 same type.
374
375 Note that once the session has been started and enabled on the tracer side,
376 it's not possible anymore to enable a new channel for that session.
377
378 .B OPTIONS:
379
380 .TP
381 .BR "\-h, \-\-help"
382 Show this help
383 .TP
384 .BR "\-\-list-options"
385 Simple listing of options
386 .TP
387 .BR "\-s, \-\-session NAME"
388 Apply on session name
389 .TP
390 .BR "\-k, \-\-kernel"
391 Apply to the kernel tracer
392 .TP
393 .BR "\-u, \-\-userspace"
394 Apply to the user-space tracer
395 .TP
396 .BR "\-\-discard"
397 Discard event when subbuffers are full (default)
398 .TP
399 .BR "\-\-overwrite"
400 Flight recorder mode : overwrites events when subbuffers are full
401 .TP
402 .BR "\-\-subbuf-size SIZE"
403 Subbuffer size in bytes {+k,+M,+G}.
404 (default UST uid: 131072, UST pid: 4096, kernel: 262144, metadata: 4096)
405 Rounded up to the next power of 2.
406
407 The minimum subbuffer size, for each tracer, is the max value between
408 the default above and the system page size. You can issue this command
409 to get the current page size on your system: \fB$ getconf PAGE_SIZE\fP
410 .TP
411 .BR "\-\-num-subbuf NUM"
412 Number of subbuffers. (default UST uid: 4, UST pid: 4, kernel: 4,
413 metadata: 2) Rounded up to the next power of 2.
414 .TP
415 .BR "\-\-switch-timer USEC"
416 Switch subbuffer timer interval in ┬Ásec.
417 (default UST uid: 0, UST pid: 0, kernel: 0, metadata: 0)
418 .TP
419 .BR "\-\-read-timer USEC"
420 Read timer interval in ┬Ásec.
421 (default UST uid: 0, UST pid: 0, kernel: 200000, metadata: 0)
422 .TP
423 .BR "\-\-output TYPE"
424 Channel output type. Possible values: mmap, splice
425 (default UST uid: mmap, UST pid: mmap, kernel: splice, metadata: mmap)
426 .TP
427 .BR "\-\-buffers-uid"
428 Use per UID buffer (\-u only). Buffers are shared between applications
429 that have the same UID.
430 .TP
431 .BR "\-\-buffers-pid"
432 Use per PID buffer (\-u only). Each application has its own buffers.
433 .TP
434 .BR "\-\-buffers-global"
435 Use shared buffer for the whole system (\-k only)
436 .TP
437 .BR "\-C, \-\-tracefile-size SIZE"
438 Maximum size of each tracefile within a stream (in bytes).
439 0 means unlimited. (default: 0)
440 .TP
441 .BR "\-W, \-\-tracefile-count COUNT"
442 Used in conjunction with \-C option, this will limit the number of files
443 created to the specified count. 0 means unlimited. (default: 0)
444
445 .B EXAMPLES:
446
447 .nf
448 $ lttng enable-channel -k -C 4096 -W 32 chan1
449 .fi
450 For each stream, the maximum size of each trace file will be 4096 bytes and
451 there will be a maximum of 32 different files. The file count is appended after
452 the stream number as seen in the following example. The last trace file is
453 smaller than 4096 since it was not completely filled.
454
455 .nf
456 ~/lttng-traces/[...]/chan1_0_0 (4096)
457 ~/lttng-traces/[...]/chan1_0_1 (4096)
458 ~/lttng-traces/[...]/chan1_0_2 (3245)
459 ~/lttng-traces/[...]/chan1_1_0 (4096)
460 ...
461 .fi
462
463 .nf
464 $ lttng enable-channel -k -C 4096
465 .fi
466 This will create trace files of 4096 bytes and will create new ones as long as
467 there is data available.
468 .RE
469 .PP
470
471 .PP
472 \fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]
473 .RS
474 Enable tracing event
475
476 A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is
477 omitted, a default channel named '\fBchannel0\fP' is created and the event is
478 added to it. If \fB\-c, \-\-channel\fP is omitted, but a non-default
479 channel already exists within the session, an error is returned. For the
480 user-space tracer, using \fB\-a, \-\-all\fP is the same as using the
481 wildcard "*".
482
483 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
484 file.
485
486 .B OPTIONS:
487
488 .TP
489 .BR "\-h, \-\-help"
490 Show summary of possible options and commands.
491 .TP
492 .BR "\-\-list-options"
493 Simple listing of options
494 .TP
495 .BR "\-s, \-\-session NAME"
496 Apply on session name
497 .TP
498 .BR "\-c, \-\-channel NAME"
499 Apply on channel name
500 .TP
501 .BR "\-a, \-\-all"
502 Enable all tracepoints and syscalls. This actually enables a single
503 wildcard event "*".
504 .TP
505 .BR "\-k, \-\-kernel"
506 Apply for the kernel tracer
507 .TP
508 .BR "\-u, \-\-userspace"
509 Apply for the user-space tracer
510 .TP
511 .BR "\-j, \-\-jul"
512 Apply for Java application using Java Util Logging interface (JUL)
513 .TP
514 .BR "\-\-tracepoint"
515 Tracepoint event (default). Userspace tracer supports wildcards at the end
516 of string. Don't forget to quote to deal with bash expansion.
517 e.g.:
518 .nf
519 "*"
520 "app_component:na*"
521 .fi
522 .TP
523 .BR "\-\-loglevel NAME"
524 Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h).
525 For the JUL domain, the loglevel ranges are detailed with the \-\-help
526 option thus starting from SEVERE to FINEST.
527 .TP
528 .BR "\-\-loglevel-only NAME"
529 Tracepoint loglevel (only this loglevel).
530 The loglevel or loglevel-only options should be combined with a
531 tracepoint name or tracepoint wildcard.
532 .TP
533 .BR "\-\-probe (addr | symbol | symbol+offset)"
534 Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...)
535 or hexadecimal (0xNNN...)
536 .TP
537 .BR "\-\-function (addr | symbol | symbol+offset)"
538 Dynamic function entry/return probe. Addr and offset can be octal
539 (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...)
540 .TP
541 .BR "\-\-syscall"
542 System call event. Enabling syscalls tracing (kernel tracer), you will
543 not be able to disable them with disable-event. This is a known
544 limitation. You can disable the entire channel to do the trick.
545 .TP
546 .BR "\-\-filter 'expression'"
547 Set a filter on a newly enabled event. Filter expression on event
548 fields and context. The event will be recorded if the filter's
549 expression evaluates to TRUE. Only specify on first activation of a
550 given event within a session.
551 Specifying a filter is only allowed when enabling events within a session before
552 tracing is started. If the filter fails to link with the event
553 within the traced domain, the event will be discarded.
554 Filtering is currently only implemented for the user-space tracer.
555
556 Expression examples:
557
558 .nf
559 'intfield > 500 && intfield < 503'
560 '(strfield == "test" || intfield != 10) && intfield > 33'
561 'doublefield > 1.1 && intfield < 5.3'
562 .fi
563
564 Wildcards are allowed at the end of strings:
565 'seqfield1 == "te*"'
566 In string literals, the escape character is a '\\'. Use '\\*' for
567 the '*' character, and '\\\\' for the '\\' character sequence. Wildcard
568 matches any sequence of characters, including an empty sub-string
569 (matches 0 or more characters).
570
571 Context information can be used for filtering. The examples below shows
572 usage of context filtering on the process name (using a wildcard), process ID
573 range, and unique thread ID. The process and thread IDs of
574 running applications can be found under columns "PID" and "LWP" of the
575 "ps -eLf" command.
576
577 .nf
578 '$ctx.procname == "demo*"'
579 '$ctx.vpid >= 4433 && $ctx.vpid < 4455'
580 '$ctx.vtid == 1234'
581 .fi
582
583 .TP
584 .BR "\-x, \-\-exclude LIST"
585 Add exclusions to UST tracepoints:
586 Events that match any of the items in the comma-separated LIST are not
587 enabled, even if they match a wildcard definition of the event.
588
589 This option is also applicable with the \fB\-a, \-\-all\fP option,
590 in which case all UST tracepoints are enabled except the ones whose
591 names match any of the items in LIST.
592 .RE
593 .PP
594
595 .PP
596 \fBdisable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
597 .RS
598 Disable tracing channel
599
600 Disabling a channel disables the tracing of all of the channel's events. A channel
601 can be reenabled by calling \fBlttng enable-channel NAME\fP again.
602
603 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
604 file.
605
606 .B OPTIONS:
607
608 .TP
609 .BR "\-h, \-\-help"
610 Show summary of possible options and commands.
611 .TP
612 .BR "\-\-list-options"
613 Simple listing of options
614 .TP
615 .BR "\-s, \-\-session NAME"
616 Apply on session name
617 .TP
618 .BR "\-k, \-\-kernel"
619 Apply for the kernel tracer
620 .TP
621 .BR "\-u, \-\-userspace"
622 Apply for the user-space tracer
623 .RE
624 .PP
625
626 .PP
627 \fBdisable-event\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
628 .RS
629 Disable tracing event
630
631 The event, once disabled, can be re-enabled by calling \fBlttng enable-event
632 NAME\fP again.
633
634 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
635 file.
636
637 If \fB\-c, \-\-channel\fP is omitted, the default channel name is used.
638 If \fB\-c, \-\-channel\fP is omitted, but a non-default channel already
639 exists within the session, an error is returned.
640
641 .B OPTIONS:
642
643 .TP
644 .BR "\-h, \-\-help"
645 Show summary of possible options and commands.
646 .TP
647 .BR "\-\-list-options"
648 Simple listing of options
649 .TP
650 .BR "\-s, \-\-session NAME"
651 Apply on session name
652 .TP
653 .BR "\-c, \-\-channel NAME"
654 Apply on channel name
655 .TP
656 .BR "\-a, \-\-all-events"
657 Disable all events. This does NOT disable "*" but rather every known
658 events of the session.
659 .TP
660 .BR "\-k, \-\-kernel"
661 Apply for the kernel tracer
662 .TP
663 .BR "\-u, \-\-userspace"
664 Apply for the user-space tracer
665 .TP
666 .BR "\-j, \-\-jul"
667 Apply for Java application using Java Util Logging interface (JUL)
668 .RE
669 .PP
670
671 .PP
672 \fBlist\fP [OPTIONS] [SESSION [SESSION OPTIONS]]
673 .RS
674 List tracing session information.
675
676 With no arguments, it will list available tracing session(s).
677
678 With the session name, it will display the details of the session including
679 the trace file path, the associated channels and their state (activated
680 and deactivated), the activated events and more.
681
682 With \-k alone, it will list all available kernel events (except the system
683 calls events).
684 With \-j alone, the available JUL event from registered application will be
685 list. The event corresponds to the Logger name in the Java JUL application.
686 With \-u alone, it will list all available user-space events from registered
687 applications. Here is an example of 'lttng list \-u':
688
689 .nf
690 PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello
691 ust_tests_hello:tptest_sighandler (type: tracepoint)
692 ust_tests_hello:tptest (type: tracepoint)
693 .fi
694
695 You can now enable any event listed by using the name :
696 \fBust_tests_hello:tptest\fP.
697
698 .B OPTIONS:
699
700 .TP
701 .BR "\-h, \-\-help"
702 Show summary of possible options and commands.
703 .TP
704 .BR "\-\-list-options"
705 Simple listing of options
706 .TP
707 .BR "\-k, \-\-kernel"
708 Select kernel domain
709 .TP
710 .BR "\-u, \-\-userspace"
711 Select user-space domain.
712 .TP
713 .BR "\-j, \-\-jul"
714 Apply for Java application using JUL
715 .TP
716 .BR "\-f, \-\-fields"
717 List event fields
718
719 .PP
720 .B SESSION OPTIONS:
721
722 .TP
723 .BR "\-c, \-\-channel NAME"
724 List details of a channel
725 .TP
726 .BR "\-d, \-\-domain"
727 List available domain(s)
728 .RE
729 .PP
730
731 .PP
732 \fBset-session\fP NAME [OPTIONS]
733 .RS
734 Set current session name
735
736 Will change the session name in the .lttngrc file.
737
738 .B OPTIONS:
739
740 .TP
741 .BR "\-h, \-\-help"
742 Show summary of possible options and commands.
743 .TP
744 .BR "\-\-list-options"
745 Simple listing of options
746 .RE
747 .PP
748
749 .PP
750 \fBsnapshot\fP [OPTIONS] ACTION
751 .RS
752 Snapshot command for LTTng session.
753
754 .B OPTIONS:
755
756 .TP
757 .BR "\-h, \-\-help"
758 Show summary of possible options and commands.
759 .TP
760 .BR "\-\-list-options"
761 Simple listing of options
762
763 .PP
764 .B ACTION:
765
766 .TP
767 \fBadd-output\fP [-m <SIZE>] [-s <NAME>] [-n <NAME>] <URL> | -C <URL> -D <URL>
768
769 Setup and add an snapshot output for a session. Output are the destination
770 where the snapshot will be sent. Only one output is permitted. To change it,
771 you'll need to delete it and add back the new one.
772
773 .TP
774 \fBdel-output\fP ID | NAME [-s <NAME>]
775
776 Delete an output for a session using the ID. You can either specify the
777 output's ID that can be found with list-output or the name.
778
779 .TP
780 \fBlist-output\fP [-s <NAME>]
781
782 List the output of a session. Attributes of the output are printed.
783
784 .TP
785 \fBrecord\fP [-m <SIZE>] [-s <NAME>] [-n <NAME>] [<URL> | -C <URL> -D <URL>]
786
787 Snapshot a session's buffer(s) for all domains. If an URL is specified, it is
788 used instead of a previously added output. Specifying only a name or/and a max
789 size will override the current output values. For instance, you can record a
790 snapshot with a custom maximum size or with a different name.
791
792 .nf
793 $ lttng snapshot add-output -n mysnapshot file:///data/snapshot
794 [...]
795 $ lttng snapshot record -n new_name_snapshot
796 .fi
797
798 The above will create a snapshot in /data/snapshot/new_name_snapshot* directory
799 rather then in mysnapshot*/
800
801 .PP
802 .B DETAILED ACTION OPTIONS
803
804 .TP
805 .BR "\-s, \-\-session NAME"
806 Apply to session name.
807 .TP
808 .BR "\-n, \-\-name NAME"
809 Name of the snapshot's output.
810 .TP
811 .BR "\-m, \-\-max-size SIZE"
812 Maximum size in bytes of the snapshot. The maxium size does not include the
813 metadata file. Human readable format is accepted: {+k,+M,+G}. For instance,
814 \-\-max-size 5M
815 .TP
816 .BR "\-C, \-\-ctrl-url URL"
817 Set control path URL. (Must use -D also)
818 .TP
819 .BR "\-D, \-\-data-url URL"
820 Set data path URL. (Must use -C also)
821 .RE
822 .PP
823
824 .PP
825 \fBstart\fP [NAME] [OPTIONS]
826 .RS
827 Start tracing
828
829 It will start tracing for all tracers for a specific tracing session.
830 If NAME is omitted, the session name is taken from the .lttngrc file.
831
832 .B OPTIONS:
833
834 .TP
835 .BR "\-h, \-\-help"
836 Show summary of possible options and commands.
837 .TP
838 .BR "\-\-list-options"
839 Simple listing of options
840 .RE
841 .PP
842
843 .PP
844 \fBstop\fP [NAME] [OPTIONS]
845 .RS
846 Stop tracing
847
848 It will stop tracing for all tracers for a specific tracing session. Before
849 returning, the command checks for data availability meaning that it will wait
850 until the trace is readable for the session. Use \-\-no-wait to avoid this
851 behavior.
852
853 If NAME is omitted, the session name is taken from the .lttngrc file.
854
855 .B OPTIONS:
856
857 .TP
858 .BR "\-h, \-\-help"
859 Show summary of possible options and commands.
860 .TP
861 .BR "\-\-list-options"
862 Simple listing of options
863 .TP
864 .BR "\-\-no-wait"
865 Don't wait for data availability.
866 .RE
867 .PP
868
869 .PP
870 \fBversion\fP
871 .RS
872 Show version information
873
874 .B OPTIONS:
875
876 .TP
877 .BR "\-h, \-\-help"
878 Show summary of possible options and commands.
879 .TP
880 .BR "\-\-list-options"
881 Simple listing of options
882 .RE
883 .PP
884
885 .PP
886 \fBview\fP [SESSION_NAME] [OPTIONS]
887 .RS
888 View traces of a tracing session. By default, the babeltrace viewer
889 will be used for text viewing. If SESSION_NAME is omitted, the session
890 name is taken from the .lttngrc file.
891
892 .B OPTIONS:
893
894 .TP
895 .BR "\-h, \-\-help"
896 Show this help
897 .TP
898 .BR "\-\-list-options"
899 Simple listing of options
900 .TP
901 .BR "\-t, \-\-trace-path PATH"
902 Trace directory path for the viewer
903 .TP
904 .BR "\-e, \-\-viewer CMD"
905 Specify viewer and/or options to use This will completely override the
906 default viewers so please make sure to specify the full command. The
907 trace directory path of the session will be appended at the end to the
908 arguments
909 .RE
910 .PP
911
912 .SH "JUL DOMAIN"
913 This section explains the JUL domain (\-j, \-\-jul) where JUL stands for Java
914 Util Logging. You can use that feature by using the \fBliblttng-ust-jul.so\fP
915 from the lttng-ust(3) project.
916
917 The LTTng Java Agent uses JNI to link the UST tracer to the Java application
918 that uses the agent. Thus, it behaves similarly to the UST domain (\-u). When
919 enabling events with the JUL domain, you enable a Logger name that will then be
920 mapped to a default UST tracepoint called \fBlttng_jul:jul_event\fP in the
921 \fBlttng_jul_channel\fP. Using the lttng-ctl API, any JUL events must use the
922 tracepoint event type (same as \-\-tracepoint).
923
924 Because of the default immutable channel (\fBlttng_jul_channel\fP), the
925 \fBenable-channel\fP command CAN NOT be used with the JUL domain thus not
926 having any \-j option.
927
928 For JUL event, loglevels are supported with the JUL ABI values. Use \fBlttng
929 enable-event \-h\fP to list them. Wildcards are NOT supported except the "*"
930 meaning all events (same as \-a).
931
932 Exactly like the UST domain, if the Java application has the same UID as you,
933 you can trace it. Same goes for the tracing group accessing root applications.
934
935 Finally, you can list every Logger name that are available from JUL registered
936 applications to the session daemon by using \fBlttng list \-j\fP.
937
938 Here is an example on how to use this domain.
939
940 .nf
941 $ lttng list -j
942 [...]
943 $ lttng create aSession
944 $ lttng enable-event -s aSession -j MyCustomLoggerName
945 $ lttng start
946 .fi
947
948 More information can be found in the lttng-ust documentation, see
949 java-util-logging.txt
950 .PP
951
952 .SH "EXIT VALUES"
953 .PP
954 On success 0 is returned and a positive value on error. Value of 1 means a command
955 error, 2 an undefined command, 3 a fatal error and 4 a command warning meaning that
956 something went wrong during the command.
957
958 Any other value above 10, please refer to
959 .BR "<lttng/lttng-error.h>"
960 for a detailed list or use lttng_strerror() to get a human readable string of
961 the error code.
962 .PP
963
964 .SH "ENVIRONMENT VARIABLES"
965
966 .PP
967 Note that all command line options override environment variables.
968 .PP
969
970 .PP
971 .IP "LTTNG_SESSIOND_PATH"
972 Allows one to specify the full session daemon binary path to lttng command line
973 tool. You can also use \-\-sessiond-path option having the same effect.
974 .PP
975
976 .SH "SEE ALSO"
977 .BR babeltrace(1),
978 .BR lttng-ust(3),
979 .BR lttng-sessiond(8),
980 .BR lttng-relayd(8),
981
982 .SH "BUGS"
983
984 .PP
985 If you encounter any issues or usability problem, please report it on our
986 mailing list <lttng-dev@lists.lttng.org> to help improve this project or
987 at https://bugs.lttng.org which is a bugtracker.
988 .PP
989
990 .SH "CREDITS"
991
992 .PP
993 lttng is distributed under the GNU General Public License version 2. See the file
994 COPYING for details.
995 .PP
996 A Web site is available at http://lttng.org for more information on the LTTng
997 project.
998 .PP
999 You can also find our git tree at http://git.lttng.org.
1000 .PP
1001 Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
1002 .PP
1003 You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
1004 .PP
1005 .SH "THANKS"
1006
1007 .PP
1008 Thanks to Yannick Brosseau without whom this project would never have been so
1009 lean and mean! Also thanks to the Ericsson teams working on tracing which
1010 helped us greatly with detailed bug reports and unusual test cases.
1011
1012 Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
1013 maintainer) and Jon Bernard for our Debian packages.
1014
1015 Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
1016 Montreal for the LTTng journey.
1017 .PP
1018 .SH "AUTHORS"
1019
1020 .PP
1021 lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
1022 David Goulet. More people have since contributed to it. It is currently
1023 maintained by David Goulet <dgoulet@efficios.com>.
1024 .PP
This page took 0.049128 seconds and 4 git commands to generate.