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