1 .TH "LTTNG" "1" "May 13th, 2014" "" ""
4 lttng \(em LTTng 2.x tracer control command line tool
9 lttng [OPTIONS] <COMMAND>
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.
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
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.
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.
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.
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).
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.
56 Show summary of possible options and commands.
58 .BR "\-v, \-\-verbose"
60 Three levels of verbosity are available which are triggered by putting additional v to
61 the option (\-vv or \-vvv)
64 Suppress all messages (even errors).
66 .BR "\-g, \-\-group NAME"
67 Set unix tracing group name. (default: tracing)
69 .BR "\-n, \-\-no-sessiond"
70 Don't automatically spawn a session daemon.
72 .BR "\-\-sessiond\-path PATH"
73 Set session daemon full binary path.
75 .BR "\-\-list\-options"
76 Simple listing of lttng options.
78 .BR "\-\-list\-commands"
79 Simple listing of lttng commands.
86 Machine interface (MI) mode converts the traditional pretty printing to a
87 machine output syntax. MI mode provides a format change-resistant way to access
88 information generated via the lttng command line.
90 When using MI mode, the data is printed on \fBstdout\fP. Error and warning are
91 printed on \fBstderr\fP with the pretty print default format.
93 If any errors occur during the execution of a command, the return value of the
94 command will be different than zero. In this case, lttng does NOT guarantee the
95 syntax and data validity of the generated MI output.
97 For XML output type, a schema definition (XSD) file used for validation can be
98 found under src/common/mi_lttng.xsd
103 \fBadd-context\fP [OPTIONS]
105 Add context to event(s) and/or channel(s).
107 A context is basically extra information appended to a channel. For instance,
108 you could ask the tracer to add the PID information for all events in a
109 channel. You can also add performance monitoring unit counters (perf PMU) using
112 For example, this command will add the context information 'prio' and two per-CPU
113 perf counters (hardware branch misses and cache misses), to all events in the trace
117 # lttng add-context \-k \-t prio \-t perf:cpu:branch-misses \\
118 \-t perf:cpu:cache-misses
121 Please take a look at the help (\-h/\-\-help) for a detailed list of available
124 Perf counters are available as per-CPU ("perf:cpu:...") and per-thread
125 ("perf:thread:...") counters. Currently, per-CPU counters can only be
126 used with the kernel tracing domain, and per-thread counters can only be
127 used with the UST tracing domain.
129 If no channel is given (\-c), the context is added to all channels that were
130 already enabled. If the session has no channel, a default channel is created.
131 Otherwise the context will be added only to the given channel (\-c).
133 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
140 Show summary of possible options and commands.
142 .BR "\-s, \-\-session NAME"
143 Apply on session name.
145 .BR "\-c, \-\-channel NAME"
146 Apply on channel name.
148 .BR "\-k, \-\-kernel"
149 Apply for the kernel tracer
151 .BR "\-u, \-\-userspace"
152 Apply for the user-space tracer
154 .BR "\-t, \-\-type TYPE"
155 Context type. You can repeat this option on the command line. Please
156 use "lttng add-context \-h" to list all available types.
161 \fBcalibrate\fP [OPTIONS]
163 Quantify LTTng overhead
165 The LTTng calibrate command can be used to find out the combined average
166 overhead of the LTTng tracer and the instrumentation mechanisms used. This
167 overhead can be calibrated in terms of time or using any of the PMU performance
168 counter available on the system.
170 For now, the only calibration implemented is that of the kernel function
171 instrumentation (kretprobes).
173 * Calibrate kernel function instrumentation
175 Let's use an example to show this calibration. We use an i7 processor with 4
176 general-purpose PMU registers. This information is available by issuing dmesg,
177 looking for "generic registers".
179 This sequence of commands will gather a trace executing a kretprobe hooked on
180 an empty function, gathering PMU counters LLC (Last Level Cache) misses
181 information (see lttng add-context \-\-help to see the list of available PMU
185 # lttng create calibrate-function
186 # lttng enable-event calibrate \-\-kernel \\
187 \-\-function lttng_calibrate_kretprobe
188 # lttng add-context \-\-kernel \-t perf:cpu:LLC-load-misses \\
189 \-t perf:cpu:LLC-store-misses \\
190 \-t perf:cpu:LLC-prefetch-misses
192 # for a in $(seq 1 10); do \\
193 lttng calibrate \-\-kernel \-\-function;
196 # babeltrace $(ls \-1drt ~/lttng-traces/calibrate-function-* \\
200 The output from babeltrace can be saved to a text file and opened in a
201 spreadsheet (e.g. oocalc) to focus on the per-PMU counter delta between
202 consecutive "calibrate_entry" and "calibrate_return" events. Note that these
203 counters are per-CPU, so scheduling events would need to be present to account
204 for migration between CPU. Therefore, for calibration purposes, only events
205 staying on the same CPU must be considered.
207 The average result, for the i7, on 10 samples:
211 perf_LLC_load_misses: 5.0 0.577
212 perf_LLC_store_misses: 1.6 0.516
213 perf_LLC_prefetch_misses: 9.0 14.742
216 As we can notice, the load and store misses are relatively stable across runs
217 (their standard deviation is relatively low) compared to the prefetch misses.
218 We can conclude from this information that LLC load and store misses can be
219 accounted for quite precisely, but prefetches within a function seems to behave
220 too erratically (not much causality link between the code executed and the CPU
221 prefetch activity) to be accounted for.
227 Show summary of possible options and commands.
229 .BR "\-k, \-\-kernel"
230 Apply for the kernel tracer
232 .BR "\-u, \-\-userspace"
233 Apply for the user-space tracer
236 Dynamic function entry/return probe (default)
241 \fBcreate\fP [NAME] [OPTIONS]
243 Create tracing session.
245 A tracing session contains channel(s) which contains event(s). It is domain
246 agnostic, meaning that channels and events can be enabled for the
247 user-space tracer and/or the kernel tracer. It acts like a container
248 aggregating multiple tracing sources.
250 On creation, a \fB.lttngrc\fP file is created in your $HOME directory
251 containing the current session name. If NAME is omitted, a session name is
252 automatically created having this form: 'auto-yyyymmdd-hhmmss'.
254 If no \fB\-o, \-\-output\fP is specified, the traces will be written in
257 The $HOME environment variable can be overridden by defining the environment
258 variable LTTNG_HOME. This is useful when the user running the commands has
259 a non-writeable home directory.
261 The session name MUST NOT contain the character '/'.
267 Show summary of possible options and commands.
269 .BR "\-\-list-options"
270 Simple listing of options
272 .BR "\-o, \-\-output PATH"
273 Specify output path for traces
276 Traces will not be output
279 Set the session in snapshot mode. Created in no-output mode and uses the
280 URL, if one is specified, as the default snapshot output. Every channel will be set
281 in overwrite mode and with mmap output (splice not supported).
283 .BR "\-\-live [USEC]"
284 Set the session exclusively in live mode. The parameter is the delay in micro
285 seconds before the data is flushed and streamed. The live mode allows you to
286 stream the trace and view it while it's being recorded by any tracer. For that,
287 you need a lttng-relayd and this session requires a network URL (\-U or
288 \-C/\-D). If no USEC nor URL is provided, the default is to use a timer value
289 set to 1000000 and the network URL set to net://127.0.0.1.
291 To read a live session, you can use babeltrace(1) or the live streaming
292 protocol in doc/live-reading-protocol.txt. Here is an example:
295 $ lttng-relayd -o /tmp/lttng
296 $ lttng create --live 200000 -U net://localhost
297 $ lttng enable-event -a --userspace
301 After the start, you'll be able to read the events while they are being
302 recorded in /tmp/lttng.
305 .BR "\-U, \-\-set-url=URL"
306 Set URL for the consumer output destination. It is persistent for the
307 session lifetime. Redo the command to change it. This will set both data
308 and control URL for network.
310 .BR "\-C, \-\-ctrl-url=URL"
311 Set control path URL. (Must use -D also)
313 .BR "\-D, \-\-data-url=URL"
314 Set data path URL. (Must use -C also)
316 Using these options, each API call can be controlled individually. For
317 instance, \-C does not enable the consumer automatically. You'll need the \-e
322 proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH]
324 Supported protocols are (proto):
327 Local filesystem full path.
331 This will use the default network transport layer which is TCP for both
332 control (PORT1) and data port (PORT2). The default ports are
333 respectively 5342 and 5343. Note that net[6]:// is not yet supported.
337 Can only be used with -C and -D together
339 NOTE: IPv6 address MUST be enclosed in brackets '[]' (rfc2732)
344 # lttng create -U net://192.168.1.42
346 Uses TCP and default ports for the given destination.
349 # lttng create -U net6://[fe80::f66d:4ff:fe53:d220]
351 Uses TCP, default ports and IPv6.
354 # lttng create s1 -U net://myhost.com:3229
356 Create session s1 and set its consumer to myhost.com on port 3229 for control.
361 \fBdestroy\fP [NAME] [OPTIONS]
363 Teardown tracing session
365 Free memory on the session daemon and tracer side. It's gone!
367 If NAME is omitted, the session name is taken from the .lttngrc file.
373 Show summary of possible options and commands.
378 .BR "\-\-list-options"
379 Simple listing of options
384 \fBenable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
386 Enable tracing channel
388 To enable an event, you must enable both the event and the channel that
391 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
394 Exactly one of \-k or -u must be specified.
396 It is important to note that if a certain type of buffers is used, the session
397 will be set with that type and all other subsequent channel needs to have the
400 Note that once the session has been started and enabled on the tracer side,
401 it's not possible anymore to enable a new channel for that session.
409 .BR "\-\-list-options"
410 Simple listing of options
412 .BR "\-s, \-\-session NAME"
413 Apply on session name
415 .BR "\-k, \-\-kernel"
416 Apply to the kernel tracer
418 .BR "\-u, \-\-userspace"
419 Apply to the user-space tracer
422 Discard event when subbuffers are full (default)
425 Flight recorder mode: overwrites events when subbuffers are full. The
426 number of subbuffer must be 2 or more.
428 .BR "\-\-subbuf-size SIZE"
429 Subbuffer size in bytes {+k,+M,+G}.
430 (default UST uid: 131072, UST pid: 4096, kernel: 262144, metadata: 4096)
431 Rounded up to the next power of 2.
433 The minimum subbuffer size, for each tracer, is the max value between
434 the default above and the system page size. You can issue this command
435 to get the current page size on your system: \fB$ getconf PAGE_SIZE\fP
437 .BR "\-\-num-subbuf NUM"
438 Number of subbuffers. (default UST uid: 4, UST pid: 4, kernel: 4,
439 metadata: 2) Rounded up to the next power of 2.
441 .BR "\-\-switch-timer USEC"
442 Switch subbuffer timer interval in µsec.
443 (default UST uid: 0, UST pid: 0, kernel: 0, metadata: 0)
445 .BR "\-\-read-timer USEC"
446 Read timer interval in µsec.
447 (default UST uid: 0, UST pid: 0, kernel: 200000, metadata: 0)
449 .BR "\-\-output TYPE"
450 Channel output type. Possible values: mmap, splice
451 (default UST uid: mmap, UST pid: mmap, kernel: splice, metadata: mmap)
453 .BR "\-\-buffers-uid"
454 Use per UID buffer (\-u only). Buffers are shared between applications
455 that have the same UID.
457 .BR "\-\-buffers-pid"
458 Use per PID buffer (\-u only). Each application has its own buffers.
460 .BR "\-\-buffers-global"
461 Use shared buffer for the whole system (\-k only)
463 .BR "\-C, \-\-tracefile-size SIZE"
464 Maximum size of each tracefile within a stream (in bytes).
465 0 means unlimited. (default: 0)
466 Note: traces generated with this option may inaccurately report
467 discarded events as of CTF 1.8.
469 .BR "\-W, \-\-tracefile-count COUNT"
470 Used in conjunction with \-C option, this will limit the number of files
471 created to the specified count. 0 means unlimited. (default: 0)
476 $ lttng enable-channel -k -C 4096 -W 32 chan1
478 For each stream, the maximum size of each trace file will be 4096 bytes and
479 there will be a maximum of 32 different files. The file count is appended after
480 the stream number as seen in the following example. The last trace file is
481 smaller than 4096 since it was not completely filled.
484 ~/lttng-traces/[...]/chan1_0_0 (4096)
485 ~/lttng-traces/[...]/chan1_0_1 (4096)
486 ~/lttng-traces/[...]/chan1_0_2 (3245)
487 ~/lttng-traces/[...]/chan1_1_0 (4096)
492 $ lttng enable-channel -k -C 4096
494 This will create trace files of 4096 bytes and will create new ones as long as
495 there is data available.
500 \fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]
504 A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is
505 omitted, a default channel named '\fBchannel0\fP' is created and the event is
506 added to it. If \fB\-c, \-\-channel\fP is omitted, but a non-default
507 channel already exists within the session, an error is returned. For the
508 user-space tracer, using \fB\-a, \-\-all\fP is the same as using the
511 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
518 Show summary of possible options and commands.
520 .BR "\-\-list-options"
521 Simple listing of options
523 .BR "\-s, \-\-session NAME"
524 Apply on session name
526 .BR "\-c, \-\-channel NAME"
527 Apply on channel name
530 Enable all tracepoints and syscalls. This actually enables a single
533 .BR "\-k, \-\-kernel"
534 Apply for the kernel tracer
536 .BR "\-u, \-\-userspace"
537 Apply for the user-space tracer
540 Apply for Java application using Java Util Logging interface (JUL)
543 Apply for Java application using LOG4J
546 Tracepoint event (default). Userspace tracer supports wildcards at the end
547 of string. Don't forget to quote to deal with bash expansion.
554 .BR "\-\-loglevel NAME"
555 Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h).
556 For the JUL domain, the loglevel ranges are detailed with the \-\-help
557 option thus starting from SEVERE to FINEST.
559 .BR "\-\-loglevel-only NAME"
560 Tracepoint loglevel (only this loglevel).
561 The loglevel or loglevel-only options should be combined with a
562 tracepoint name or tracepoint wildcard.
564 .BR "\-\-probe (addr | symbol | symbol+offset)"
565 Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...)
566 or hexadecimal (0xNNN...)
568 .BR "\-\-function (addr | symbol | symbol+offset)"
569 Dynamic function entry/return probe. Addr and offset can be octal
570 (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...)
573 System call event. Enabling syscalls tracing (kernel tracer), you will
574 not be able to disable them with disable-event. This is a known
575 limitation. You can disable the entire channel to do the trick. Also note
576 that per-syscall selection is not supported yet. Use with "-a" to enable
579 .BR "\-\-filter 'expression'"
580 Set a filter on a newly enabled event. Filter expression on event
581 fields and context. The event will be recorded if the filter's
582 expression evaluates to TRUE. Only specify on first activation of a
583 given event within a session.
584 Specifying a filter is only allowed when enabling events within a session before
585 tracing is started. If the filter fails to link with the event
586 within the traced domain, the event will be discarded.
587 Filtering is currently only implemented for the user-space tracer.
592 'intfield > 500 && intfield < 503'
593 '(strfield == "test" || intfield != 10) && intfield > 33'
594 'doublefield > 1.1 && intfield < 5.3'
597 Wildcards are allowed at the end of strings:
599 In string literals, the escape character is a '\\'. Use '\\*' for
600 the '*' character, and '\\\\' for the '\\' character sequence. Wildcard
601 matches any sequence of characters, including an empty sub-string
602 (matches 0 or more characters).
604 Context information can be used for filtering. The examples below shows
605 usage of context filtering on the process name (using a wildcard), process ID
606 range, and unique thread ID. The process and thread IDs of
607 running applications can be found under columns "PID" and "LWP" of the
611 '$ctx.procname == "demo*"'
612 '$ctx.vpid >= 4433 && $ctx.vpid < 4455'
616 Context information is available to all filters whether or not the add-context
617 command has been used to add it to the event's channel, as long as the context
618 field exists for that domain. For example, the filter examples given above will
619 never fail to link: no add-context is required for the event's channel.
622 .BR "\-x, \-\-exclude LIST"
623 Add exclusions to UST tracepoints:
624 Events that match any of the items in the comma-separated LIST are not
625 enabled, even if they match a wildcard definition of the event.
627 This option is also applicable with the \fB\-a, \-\-all\fP option,
628 in which case all UST tracepoints are enabled except the ones whose
629 names match any of the items in LIST.
634 \fBdisable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
636 Disable tracing channel
638 Disabling a channel disables the tracing of all of the channel's events. A channel
639 can be re-enabled by calling \fBlttng enable-channel NAME\fP again.
641 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
648 Show summary of possible options and commands.
650 .BR "\-\-list-options"
651 Simple listing of options
653 .BR "\-s, \-\-session NAME"
654 Apply on session name
656 .BR "\-k, \-\-kernel"
657 Apply for the kernel tracer
659 .BR "\-u, \-\-userspace"
660 Apply for the user-space tracer
665 \fBdisable-event\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
667 Disable tracing event
669 The event, once disabled, can be re-enabled by calling \fBlttng enable-event
672 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
675 If \fB\-c, \-\-channel\fP is omitted, the default channel name is used.
676 If \fB\-c, \-\-channel\fP is omitted, but a non-default channel already
677 exists within the session, an error is returned.
683 Show summary of possible options and commands.
685 .BR "\-\-list-options"
686 Simple listing of options
688 .BR "\-s, \-\-session NAME"
689 Apply on session name
691 .BR "\-c, \-\-channel NAME"
692 Apply on channel name
694 .BR "\-a, \-\-all-events"
695 Disable all events. This does NOT disable "*" but rather every known
696 events of the session.
698 .BR "\-k, \-\-kernel"
699 Apply for the kernel tracer
701 .BR "\-u, \-\-userspace"
702 Apply for the user-space tracer
705 Apply for Java application using Java Util Logging interface (JUL)
708 Apply for Java application using LOG4J
713 \fBlist\fP [OPTIONS] [SESSION [SESSION OPTIONS]]
715 List tracing session information.
717 With no arguments, it will list available tracing session(s).
719 With the session name, it will display the details of the session including
720 the trace file path, the associated channels and their state (activated
721 and deactivated), the activated events and more.
723 With \-k alone, it will list all available kernel events (except the system
725 With \-j alone, the available JUL event from registered application will be
726 list. The event corresponds to the Logger name in the Java JUL application.
727 With \-u alone, it will list all available user-space events from registered
728 applications. Here is an example of 'lttng list \-u':
731 PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello
732 ust_tests_hello:tptest_sighandler (type: tracepoint)
733 ust_tests_hello:tptest (type: tracepoint)
736 You can now enable any event listed by using the name :
737 \fBust_tests_hello:tptest\fP.
743 Show summary of possible options and commands.
745 .BR "\-\-list-options"
746 Simple listing of options
748 .BR "\-k, \-\-kernel"
751 .BR "\-u, \-\-userspace"
752 Select user-space domain.
755 Apply for Java application using JUL
759 Apply for Java application using LOG4J
760 .BR "\-f, \-\-fields"
767 .BR "\-c, \-\-channel NAME"
768 List details of a channel
770 .BR "\-d, \-\-domain"
771 List available domain(s)
776 \fBload\fP [OPTIONS] [NAME]
778 Load tracing session configuration
780 If NAME is omitted, all session configurations found in both the user's session
781 configuration directory (default: ~/.lttng/sessions/) and the system session
782 configuration directory (default: /etc/lttng/sessions/) will be loaded. Note
783 that the sessions in the user directory are loaded first and then the system
784 wide directory are loaded.
790 Show summary of possible options and commands.
793 Load all session configurations (default).
795 .BR "\-i, \-\-input-path PATH"
796 Specify the input path for session configurations. This overrides the default
797 session configuration directory.
800 Overwrite current session configuration(s) if a session of the same name
806 \fBsave\fP [OPTIONS] [SESSION]
808 Save tracing session configuration
810 If SESSION is omitted, all session configurations will be saved to individual
811 \fB.lttng\fP files under the user's session configuration directory (default:
812 ~/.lttng/sessions/). The default session configuration file naming scheme is
815 For instance, a user in the tracing group saving a session from a root session
816 daemon will save it in her/his user directory.
822 Show summary of possible options and commands.
825 Save all session configurations (default).
827 .BR "\-o, \-\-output-path PATH"
828 Specify the output path for saved sessions. This overrides the default session
829 configuration directory.
832 Overwrite session configuration file if session name clashes.
837 \fBset-session\fP NAME [OPTIONS]
839 Set current session name
841 Will change the session name in the .lttngrc file.
847 Show summary of possible options and commands.
849 .BR "\-\-list-options"
850 Simple listing of options
855 \fBsnapshot\fP [OPTIONS] ACTION
857 Snapshot command for LTTng session.
863 Show summary of possible options and commands.
865 .BR "\-\-list-options"
866 Simple listing of options
872 \fBadd-output\fP [-m <SIZE>] [-s <NAME>] [-n <NAME>] <URL> | -C <URL> -D <URL>
874 Setup and add an snapshot output for a session. Output are the destination
875 where the snapshot will be sent. Only one output is permitted. To change it,
876 you'll need to delete it and add back the new one.
879 \fBdel-output\fP ID | NAME [-s <NAME>]
881 Delete an output for a session using the ID. You can either specify the
882 output's ID that can be found with list-output or the name.
885 \fBlist-output\fP [-s <NAME>]
887 List the output of a session. Attributes of the output are printed.
890 \fBrecord\fP [-m <SIZE>] [-s <NAME>] [-n <NAME>] [<URL> | -C <URL> -D <URL>]
892 Snapshot a session's buffer(s) for all domains. If an URL is specified, it is
893 used instead of a previously added output. Specifying only a name or/and a max
894 size will override the current output values. For instance, you can record a
895 snapshot with a custom maximum size or with a different name.
898 $ lttng snapshot add-output -n mysnapshot file:///data/snapshot
900 $ lttng snapshot record -n new_name_snapshot
903 The above will create a snapshot in /data/snapshot/new_name_snapshot* directory
904 rather then in mysnapshot*/
907 .B DETAILED ACTION OPTIONS
910 .BR "\-s, \-\-session NAME"
911 Apply to session name.
913 .BR "\-n, \-\-name NAME"
914 Name of the snapshot's output.
916 .BR "\-m, \-\-max-size SIZE"
917 Maximum size in bytes of the snapshot. The maximum size does not include the
918 metadata file. Human readable format is accepted: {+k,+M,+G}. For instance,
921 The minimum size of a snapshot is computed by multiplying the total amount of
922 streams in the session by the largest subbuffer size. This is to ensure
923 fairness between channels when extracting data.
925 .BR "\-C, \-\-ctrl-url URL"
926 Set control path URL. (Must use -D also)
928 .BR "\-D, \-\-data-url URL"
929 Set data path URL. (Must use -C also)
934 \fBstart\fP [NAME] [OPTIONS]
938 It will start tracing for all tracers for a specific tracing session.
939 If NAME is omitted, the session name is taken from the .lttngrc file.
945 Show summary of possible options and commands.
947 .BR "\-\-list-options"
948 Simple listing of options
953 \fBstop\fP [NAME] [OPTIONS]
957 It will stop tracing for all tracers for a specific tracing session. Before
958 returning, the command checks for data availability meaning that it will wait
959 until the trace is readable for the session. Use \-\-no-wait to avoid this
962 If NAME is omitted, the session name is taken from the .lttngrc file.
968 Show summary of possible options and commands.
970 .BR "\-\-list-options"
971 Simple listing of options
974 Don't wait for data availability.
981 Show version information
987 Show summary of possible options and commands.
989 .BR "\-\-list-options"
990 Simple listing of options
995 \fBview\fP [SESSION_NAME] [OPTIONS]
997 View traces of a tracing session. By default, the babeltrace viewer
998 will be used for text viewing. If SESSION_NAME is omitted, the session
999 name is taken from the .lttngrc file.
1007 .BR "\-\-list-options"
1008 Simple listing of options
1010 .BR "\-t, \-\-trace-path PATH"
1011 Trace directory path for the viewer
1013 .BR "\-e, \-\-viewer CMD"
1014 Specify viewer and/or options to use This will completely override the
1015 default viewers so please make sure to specify the full command. The
1016 trace directory path of the session will be appended at the end to the
1022 This section explains the JUL domain (\-j, \-\-jul) where JUL stands for Java
1023 Util Logging. You can use that feature by using the \fBliblttng-ust-jul.so\fP
1024 from the lttng-ust(3) project.
1026 The LTTng Java Agent uses JNI to link the UST tracer to the Java application
1027 that uses the agent. Thus, it behaves similarly to the UST domain (\-u). When
1028 enabling events with the JUL domain, you enable a Logger name that will then be
1029 mapped to a default UST tracepoint called \fBlttng_jul:jul_event\fP in the
1030 \fBlttng_jul_channel\fP. Using the lttng-ctl API, any JUL events must use the
1031 tracepoint event type (same as \-\-tracepoint).
1033 Because of the default immutable channel (\fBlttng_jul_channel\fP), the
1034 \fBenable-channel\fP command CAN NOT be used with the JUL domain thus not
1035 having any \-j option.
1037 For JUL event, loglevels are supported with the JUL ABI values. Use \fBlttng
1038 enable-event \-h\fP to list them. Wildcards are NOT supported except the "*"
1039 meaning all events (same as \-a).
1041 Exactly like the UST domain, if the Java application has the same UID as you,
1042 you can trace it. Same goes for the tracing group accessing root applications.
1044 Finally, you can list every Logger name that are available from JUL registered
1045 applications to the session daemon by using \fBlttng list \-j\fP.
1047 Here is an example on how to use this domain.
1052 $ lttng create aSession
1053 $ lttng enable-event -s aSession -j MyCustomLoggerName
1057 More information can be found in the lttng-ust documentation, see
1058 java-util-logging.txt
1063 On success 0 is returned and a positive value on error. Value of 1 means a command
1064 error, 2 an undefined command, 3 a fatal error and 4 a command warning meaning that
1065 something went wrong during the command.
1067 Any other value above 10, please refer to
1068 .BR "<lttng/lttng-error.h>"
1069 for a detailed list or use lttng_strerror() to get a human readable string of
1073 .SH "ENVIRONMENT VARIABLES"
1076 Note that all command line options override environment variables.
1080 .IP "LTTNG_SESSIOND_PATH"
1081 Allows one to specify the full session daemon binary path to lttng command line
1082 tool. You can also use \-\-sessiond-path option having the same effect.
1086 .IP "LTTNG_SESSION_CONFIG_XSD_PATH"
1087 Set the path in which the \fBsession.xsd\fP session configuration schema may be
1094 .BR lttng-sessiond(8),
1095 .BR lttng-relayd(8),
1100 If you encounter any issues or usability problem, please report it on our
1101 mailing list <lttng-dev@lists.lttng.org> to help improve this project or
1102 at https://bugs.lttng.org which is a bug tracker.
1108 lttng is distributed under the GNU General Public License version 2. See the file
1109 COPYING for details.
1111 A Web site is available at http://lttng.org for more information on the LTTng
1114 You can also find our git tree at http://git.lttng.org.
1116 Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
1118 You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
1123 Thanks to Yannick Brosseau without whom this project would never have been so
1124 lean and mean! Also thanks to the Ericsson teams working on tracing which
1125 helped us greatly with detailed bug reports and unusual test cases.
1127 Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
1128 maintainer) and Jon Bernard for our Debian packages.
1130 Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
1131 Montreal for the LTTng journey.
1136 lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
1137 David Goulet. More people have since contributed to it. It is currently
1138 maintained by David Goulet <dgoulet@efficios.com>.