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