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