New UST default buffers is now per UID
[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
6b8f2e64
DG
233
234Using these options, each API call can be controlled individually. For
235instance, \-C does not enable the consumer automatically. You'll need the \-e
236option for that.
237
23d14dff 238\-U, \-\-set-url=URL
785d2d0d 239 Set URL for the consumer output destination. It is persistent for the
6b8f2e64
DG
240 session lifetime. Redo the command to change it. This will set both
241 data and control URL for network.
242\-C, \-\-ctrl-url=URL
243 Set control path URL. (Must use -D also)
244\-D, \-\-data-url=URL
245 Set data path URL. (Must use -C also)
6b8f2e64 246
785d2d0d
DG
247.B URL FORMAT:
248
249proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH]
250
251Supported protocols are (proto):
252> file://...
253 Local filesystem full path.
254
255> net://...
256 This will use the default network transport layer which is TCP for both
257 control (PORT1) and data port (PORT2). The default ports are
258 respectively 5342 and 5343. Note that net[6]:// is not yet supported.
259
260> tcp[6]://...
261 Can only be used with -C and -D together
262
263NOTE: IPv6 address MUST be enclosed in brackets '[]' (rfc2732)
6b8f2e64
DG
264
265.B EXAMPLES:
266
267# lttng create -U net://192.168.1.42
268Uses TCP and default ports for the given destination.
269
270# lttng create -U net6://[fe80::f66d:4ff:fe53:d220]
271Uses TCP, default ports and IPv6.
272
273# lttng create s1 -U net://myhost.com:3229
274Create session s1 and set its consumer to myhost.com on port 3229 for control.
6991b181
DG
275.fi
276
277.IP
278
279.IP "\fBdestroy\fP [OPTIONS] [NAME]"
280.nf
281Teardown tracing session
282
283Free memory on the session daemon and tracer side. It's gone!
284
285If NAME is omitted, the session name is taken from the .lttngrc file.
286.fi
287
288.B OPTIONS:
289
290.nf
c9e32613 291\-h, \-\-help
6991b181 292 Show summary of possible options and commands.
a3c5b534
FG
293\-a, \-\-all
294 Destroy all sessions
c9e32613 295\-\-list-options
6991b181
DG
296 Simple listing of options
297.fi
298
299.IP
300
301.IP "\fBenable-channel\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
302.nf
303Enable tracing channel
304
004f3466
DG
305To enable an event, you must enable both the event and the channel that
306contains it.
b883c01b 307
c9e32613 308If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181 309file.
7972aab2
DG
310
311It is important to note that if a certain type of buffers is used, the session
bd337b98 312will be set with that type and all other subsequent channel needs to have the
7972aab2 313same type.
bd337b98 314
d2f11c4a
DG
315Note that once the session has been started and enabled on the tracer side,
316it's not possible anymore to enable a new channel for that session.
6991b181
DG
317.fi
318
319.B OPTIONS:
320
321.nf
c9e32613 322\-h, \-\-help
6991b181 323 Show this help
c9e32613 324\-\-list-options
6991b181 325 Simple listing of options
391b9c72 326\-s, \-\-session NAME
6991b181 327 Apply on session name
c9e32613 328\-k, \-\-kernel
6991b181 329 Apply to the kernel tracer
c9e32613 330\-u, \-\-userspace
6991b181
DG
331 Apply to the user-space tracer
332
c9e32613 333\-\-discard
6991b181 334 Discard event when subbuffers are full (default)
c9e32613 335\-\-overwrite
6991b181 336 Flight recorder mode : overwrites events when subbuffers are full
391b9c72 337\-\-subbuf-size SIZE
0a9c6494
DG
338 Subbuffer size in bytes {+k,+M,+G}
339 (default UST uid: 131072, UST pid: 4096, kernel: 262144, metadata: 4096)
1cb514ce 340 Rounded up to the next power of 2.
bd337b98
DG
341
342 The minimum subbuffer size, for each tracer, is the max value between
343 the default above and the system page size. You can issue this command
344 to get the current page size on your system: \fB$ getconf PAGE_SIZE\fP
391b9c72 345\-\-num-subbuf NUM
0a9c6494 346 Number of subbuffers. (default UST uid: 4, UST pid: 4, kernel: 4, metadata: 2)
1cb514ce 347 Rounded up to the next power of 2.
391b9c72 348\-\-switch-timer USEC
0a9c6494
DG
349 Switch subbuffer timer interval in ┬Ásec.
350 (default UST uid: 0, UST pid: 0, kernel: 0, metadata: 0)
391b9c72 351\-\-read-timer USEC
0a9c6494
DG
352 Read timer interval in ┬Ásec.
353 (default UST uid: 0, UST pid: 0, kernel: 200000, metadata: 0)
391b9c72
DG
354\-\-output TYPE
355 Channel output type. Possible values: mmap, splice
0a9c6494 356 (default UST uid: mmap, UST pid: mmap, kernel: splice, metadata: mmap)
7972aab2
DG
357\-\-buffers-uid
358 Use per UID buffer (\-u only). Buffers are shared between applications
359 that have the same UID.
360\-\-buffers-pid
361 Use per PID buffer (\-u only). Each application has its own buffers.
362\-\-buffers-global
363 Use shared buffer for the whole system (\-k only)
1624d5b7 364\-C, \-\-tracefile-size SIZE
e132a0d4 365 Maximum size of each tracefile within a stream (in bytes).
0a9c6494 366 0 means unlimited. (default: 0)
1624d5b7
JD
367\-W, \-\-tracefile-count COUNT
368 Used in conjunction with \-C option, this will limit the number
0a9c6494 369 of files created to the specified count. 0 means unlimited. (default: 0)
1624d5b7
JD
370
371.B EXAMPLES:
372
373$ lttng enable-channel -C 4096 -W 32 chan1
cea28771
DG
374For each stream, the maximum size of each trace file will be 4096 bytes, and
375there will be a maximum of 32 different files. The file count is appended after
1624d5b7
JD
376the stream number as seen in the following example. The last trace file is
377smaller than 4096 since it was not completely filled.
378
379 ~/lttng-traces/[...]/chan1_0_0 (4096)
380 ~/lttng-traces/[...]/chan1_0_1 (4096)
381 ~/lttng-traces/[...]/chan1_0_2 (3245)
382 ~/lttng-traces/[...]/chan1_1_0 (4096)
383 ...
384
385$ lttng enable-channel -C 4096
386This will create trace files of 4096 bytes and will create new ones as long as
387there is data available.
6991b181
DG
388.fi
389
390.IP
391
392.IP "\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
393.nf
394Enable tracing event
395
c9e32613 396A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is
6991b181 397omitted, a default channel named '\fBchannel0\fP' is created and the event is
c9e32613 398added to it. For the user-space tracer, using \fB\-a, \-\-all\fP is the same as
6991b181
DG
399using the wildcard "*".
400
c9e32613 401If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
402file.
403.fi
404
405.B OPTIONS:
406
407.nf
c9e32613 408\-h, \-\-help
6991b181 409 Show summary of possible options and commands.
c9e32613 410\-\-list-options
6991b181 411 Simple listing of options
391b9c72 412\-s, \-\-session NAME
6991b181 413 Apply on session name
391b9c72 414\-c, \-\-channel NAME
6991b181 415 Apply on channel name
c9e32613 416\-a, \-\-all
c5650942
DG
417 Enable all tracepoints and syscalls. This actually enable a single
418 wildcard event "*".
c9e32613 419\-k, \-\-kernel
6991b181 420 Apply for the kernel tracer
c9e32613 421\-u, \-\-userspace
6991b181
DG
422 Apply for the user-space tracer
423
c9e32613 424\-\-tracepoint
6991b181
DG
425 Tracepoint event (default)
426 - userspace tracer supports wildcards at end of string. Don't forget to
427 quote to deal with bash expansion.
428 e.g.:
429 "*"
430 "app_component:na*"
391b9c72
DG
431\-\-loglevel NAME
432 Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h).
433\-\-loglevel-only NAME
434 Tracepoint loglevel (only this loglevel).
435
436 The loglevel or loglevel-only options should be combined with a
437 tracepoint name or tracepoint wildcard.
c9e32613 438\-\-probe [addr | symbol | symbol+offset]
6991b181
DG
439 Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...)
440 or hexadecimal (0xNNN...)
c9e32613 441\-\-function [addr | symbol | symbol+offset]
6991b181
DG
442 Dynamic function entry/return probe. Addr and offset can be octal
443 (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...)
c9e32613 444\-\-syscall
6b8f2e64
DG
445 System call event. Enabling syscalls tracing (kernel tracer), you will
446 not be able to disable them with disable-event. This is a known
447 limitation. You can disable the entire channel to do the trick.
9bd578f5 448
919e300c 449\-\-filter 'expression'
6b8f2e64 450 Set a filter on a newly enabled event. Filter expression on event
ee8ccafa
MD
451 fields and context. Event recording depends on evaluation. Only
452 specify on first activation of a given event within a session.
453 Filter only allowed when enabling events within a session before
454 tracing is started. If the filter fails to link with the event
455 within the traced domain, the event will be discarded.
456 Currently, filter is only implemented for the user-space tracer.
6b8f2e64
DG
457
458 Expression examples:
459
460 'intfield > 500 && intfield < 503'
461 '(stringfield == "test" || intfield != 10) && intfield > 33'
462 'doublefield > 1.1 && intfield < 5.3'
463
464 Wildcards are allowed at the end of strings:
465 'seqfield1 == "te*"'
466 In string literals, the escape character is a '\\'. Use '\\*' for
ee8ccafa
MD
467 the '*' character, and '\\\\' for the '\\' character. Wildcard
468 match any sequence of characters, including an empty sub-string
469 (match 0 or more characters).
470
471 Context information can be used for filtering. The examples
472 below show usage of context filtering on process name (with a
473 wildcard), process ID range, and unique thread ID for filtering.
474 The process and thread ID of running applications can be found
475 under columns "PID" and "LWP" of the "ps -eLf" command.
476
477 '$ctx.procname == "demo*"'
478 '$ctx.vpid >= 4433 && $ctx.vpid < 4455'
479 '$ctx.vtid == 1234'
6991b181
DG
480.fi
481
c9e32613 482.IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
6991b181
DG
483.nf
484Disable tracing channel
485
486Disabling a channel makes all event(s) in that channel to stop tracing. You can
487enable it back by calling \fBlttng enable-channel NAME\fP again.
488
c9e32613 489If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
490file.
491.fi
492
493.B OPTIONS:
494
6b8f2e64
DG
495.nf
496\-h, \-\-help
497 Show summary of possible options and commands.
498\-\-list-options
499 Simple listing of options
500\-s, \-\-session NAME
6991b181 501 Apply on session name
c9e32613 502\-k, \-\-kernel
6991b181 503 Apply for the kernel tracer
c9e32613 504\-u, \-\-userspace
6991b181
DG
505 Apply for the user-space tracer
506.fi
507
c9e32613 508.IP "\fBdisable-event\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
6991b181
DG
509.nf
510Disable tracing event
511
512The event, once disabled, can be re-enabled by calling \fBlttng enable-event
513NAME\fP again.
514
c9e32613 515If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
6991b181
DG
516file.
517.fi
518
519.B OPTIONS:
520
521.nf
c9e32613 522\-h, \-\-help
6991b181 523 Show summary of possible options and commands.
c9e32613 524\-\-list-options
6991b181 525 Simple listing of options
391b9c72 526\-s, \-\-session NAME
6991b181 527 Apply on session name
c5650942
DG
528\-a, \-\-all-events
529 Disable all events. This does NOT disable "*" but rather
530 every known events of the session.
c9e32613 531\-k, \-\-kernel
6991b181 532 Apply for the kernel tracer
c9e32613 533\-u, \-\-userspace
6991b181
DG
534 Apply for the user-space tracer
535.fi
536
c9e32613 537.IP "\fBlist\fP [\-k|\-u] [SESSION [SESSION_OPTIONS]]"
6991b181 538.nf
c9e32613 539List tracing session information.
6991b181
DG
540
541With no arguments, it will list available tracing session(s).
542
fa072eae
YB
543With the session name, it will display the details of the session including
544the trace file path, the associated channels and their state (activated
d829b38c 545and deactivated), the activated events and more.
fa072eae 546
c9e32613 547With \-k alone, it will list all available kernel events (except the system
6991b181 548calls events).
c9e32613
DG
549With \-u alone, it will list all available user-space events from registered
550applications. Here is an example of 'lttng list \-u':
6991b181
DG
551
552PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello
553 ust_tests_hello:tptest_sighandler (type: tracepoint)
554 ust_tests_hello:tptest (type: tracepoint)
555
556You can now enable any event listed by using the name :
557\fBust_tests_hello:tptest\fP.
558.fi
559
560.B OPTIONS:
561
562.nf
c9e32613 563\-h, \-\-help
6991b181 564 Show summary of possible options and commands.
c9e32613 565\-\-list-options
6991b181 566 Simple listing of options
c9e32613 567\-k, \-\-kernel
d829b38c 568 Select kernel domain
c9e32613 569\-u, \-\-userspace
6991b181
DG
570 Select user-space domain.
571
6b8f2e64
DG
572.B SESSION OPTIONS:
573
c9e32613 574\-c, \-\-channel NAME
6991b181 575 List details of a channel
c9e32613 576\-d, \-\-domain
6991b181
DG
577 List available domain(s)
578.fi
579
580.IP "\fBset-session\fP NAME"
581.nf
582Set current session name
583
584Will change the session name in the .lttngrc file.
585.fi
586
587.B OPTIONS:
588
589.nf
c9e32613 590\-h, \-\-help
6991b181 591 Show summary of possible options and commands.
c9e32613 592\-\-list-options
6991b181
DG
593 Simple listing of options
594.fi
595
596.IP
597
6b8f2e64 598.IP "\fBstart\fP [NAME] [OPTIONS]"
6991b181
DG
599.nf
600Start tracing
601
602It will start tracing for all tracers for a specific tracing session.
603
604If NAME is omitted, the session name is taken from the .lttngrc file.
605.fi
606
607.B OPTIONS:
608
609.nf
c9e32613 610\-h, \-\-help
6991b181 611 Show summary of possible options and commands.
c9e32613 612\-\-list-options
6991b181
DG
613 Simple listing of options
614.fi
615
616.IP
617
6b8f2e64 618.IP "\fBstop\fP [NAME] [OPTIONS]"
6991b181
DG
619.nf
620Stop tracing
621
391b9c72
DG
622It will stop tracing for all tracers for a specific tracing session. Before
623returning, the command checks for data availability meaning that it will wait
624until the trace is readable for the session. Use \-\-no-wait to avoid this
625behavior.
6991b181
DG
626
627If NAME is omitted, the session name is taken from the .lttngrc file.
628.fi
629
630.B OPTIONS:
631
632.nf
c9e32613 633\-h, \-\-help
6991b181 634 Show summary of possible options and commands.
c9e32613 635\-\-list-options
6991b181 636 Simple listing of options
391b9c72
DG
637\-\-no-wait
638 Don't wait for data availability.
6991b181
DG
639.fi
640
641.IP
642
643.IP "\fBversion\fP"
644.nf
645Show version information
646.fi
647
648.B OPTIONS:
649
650.nf
c9e32613 651\-h, \-\-help
6991b181 652 Show summary of possible options and commands.
c9e32613 653\-\-list-options
6991b181
DG
654 Simple listing of options
655.fi
656
657.IP
658
659.IP "\fBview\fP [SESSION_NAME] [OPTIONS]"
660.nf
661View traces of a tracing session
662
663By default, the babeltrace viewer will be used for text viewing.
664
fa072eae
YB
665If SESSION_NAME is omitted, the session name is taken from the .lttngrc file.
666
6991b181
DG
667.fi
668
669.B OPTIONS:
670
671.nf
c9e32613 672\-h, \-\-help
6991b181 673 Show this help
c9e32613 674\-\-list-options
6991b181 675 Simple listing of options
c9e32613 676\-t, \-\-trace-path PATH
6991b181 677 Trace directory path for the viewer
c9e32613 678\-e, \-\-viewer CMD
6991b181
DG
679 Specify viewer and/or options to use
680 This will completely override the default viewers so
681 please make sure to specify the full command. The trace
682 directory path of the session will be appended at the end
683 to the arguments
684.fi
685
c206d957 686.SH "EXIT VALUES"
6b8f2e64
DG
687On success 0 is returned and a positive value on error. Value of 1 means a command
688error, 2 an undefined command, 3 a fatal error and 4 a command warning meaning that
689something went wrong during the command.
c206d957 690
6b8f2e64
DG
691Any other value above 10, please refer to
692.BR <lttng/lttng-error.h>
693for a detailed list or use lttng_strerror() to get a human readable string of
694the error code.
c206d957 695
c206d957 696.PP
6991b181
DG
697.SH "ENVIRONMENT VARIABLES"
698
699.PP
700Note that all command line options override environment variables.
701.PP
702
703.PP
05833633 704.IP "LTTNG_SESSIOND_PATH"
c9e32613
DG
705Allows one to specify the full session daemon binary path to lttng command line
706tool. You can also use \-\-sessiond-path option having the same effect.
6991b181 707.SH "SEE ALSO"
6b8f2e64
DG
708.BR babeltrace(1),
709.BR lttng-ust(3),
710.BR lttng-sessiond(8),
711.BR lttng-relayd(8),
712.BR lttng-health-check(3)
6991b181
DG
713.SH "BUGS"
714
6991b181 715If you encounter any issues or usability problem, please report it on our
6b8f2e64
DG
716mailing list <lttng-dev@lists.lttng.org> to help improve this project or
717at https://bugs.lttng.org which is a bugtracker.
6991b181
DG
718.SH "CREDITS"
719
720.PP
c9e32613 721lttng is distributed under the GNU General Public License version 2. See the file
6991b181
DG
722COPYING for details.
723.PP
724A Web site is available at http://lttng.org for more information on the LTTng
725project.
726.PP
727You can also find our git tree at http://git.lttng.org.
728.PP
729Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
730.PP
731You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
732.PP
733.SH "THANKS"
734
735.PP
736Thanks to Yannick Brosseau without whom this project would never have been so
737lean and mean! Also thanks to the Ericsson teams working on tracing which
fa072eae 738helped us greatly with detailed bug reports and unusual test cases.
6991b181
DG
739
740Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
741maintainer) and Jon Bernard for our Debian packages.
742
743Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
744Montreal for the LTTng journey.
c9e32613 745.PP
6991b181
DG
746.SH "AUTHORS"
747
748.PP
749lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
750David Goulet. More people have since contributed to it. It is currently
751maintained by David Goulet <dgoulet@efficios.com>.
752.PP
This page took 0.058672 seconds and 4 git commands to generate.