prepare the 0.3 release
[lttngtop.git] / doc / lttngtop.1
CommitLineData
54645d5c 1.TH "LTTNGTOP" "1" "June 01, 2015" "" ""
661ad2e0
JD
2
3.SH "NAME"
4lttngtop \(em LTTng Trace Viewer
5
6.SH "SYNOPSIS"
7
8.PP
9.nf
10lttngtop INPUT
11.fi
12.SH "DESCRIPTION"
13
14.PP
15
16Lttngtop is a ncurses interface for reading and browsing traces recorded by the
17LTTng tracer and displaying various statistics. As of now, the cpu usage,
18performance counters and per process/file I/O bandwidth are displayed. This
19version currently only supports offline traces, but a live version is in alpha
20and will be available for testing soon.
21.SH "OPTIONS"
22
23.TP
24.BR "INPUT"
25Input trace path
26
27.SH "TRACE REQUIREMENTS"
28
29.PP
30
31LTTngTop requires that the pid, procname, tid and ppid context information
32are enabled during tracing.
26d63ddf
JD
33
34The command --create-local-session does all the required setup for a local
35trace (that must be stopped and destroyed manually by the user).
36And the command --create-live-session does all the required setup for a live
37trace on localhost (it must also be stopped and destroyed manually by the user).
661ad2e0
JD
38.PP
39
40.PP
41If you want the CPU activity view, you need the sched_switch event, if you
42want the I/O statistics, you need to enable the system call tracing, and if
43you want the performance counters, you need to enable them for the events you
44are interested in (or all of them). Note, there is a hardware limitation for the
45number of performance counter you can enable, check dmesg for information.
46.PP
47
48.PP
49The following example creates a trace with all events enabled, the mandatory context informations and
50three performance counters. It assumes that you are running as root or with a user part of the tracing group and a lttng-sessiond
51launched as root.
52.PP
53
54.nf
55lttng create lttngtop
3e06508b 56lttng enable-event -k lttng_statedump_start,lttng_statedump_end,lttng_statedump_process_state,lttng_statedump_file_descriptor,lttng_statedump_vm_map,lttng_statedump_network_interface,lttng_statedump_interrupt,sched_process_free,sched_switchsched_process_fork -s lttngtop
bab469fc
JD
57lttng enable-event -k --syscall -a -s lttngtop
58lttng add-context -k -t pid -t procname -t tid -t ppid -t perf:cache-misses -t perf:major-faults -t perf:branch-load-misses -s lttngtop
59lttng start lttngtop
661ad2e0 60sleep 10
bab469fc
JD
61lttng stop lttngtop
62lttng destroy lttngtop
661ad2e0
JD
63.fi
64
bab469fc
JD
65.SH "LIVE STREAMING"
66
67.PP
3e06508b
JD
68In addition to offline traces, LTTngTop can read traces while they are being
69recorded. The official supported way of doing live streaming is using
70lttng-tools >=2.4 and following the documentation in live-reading-howto.txt of
71lttng-tools and README-LIVE of lttngtop.
bab469fc
JD
72An other experimental way of doing live tracing is with mmap, but this requires some
73more work because is not officially supported and requires out-of-tree patches to
74lttng-tools and babeltrace.
75
76.PP
77To use the network live-reading, the user only needs to specify the relayd hostname
78or IP address with the option -r. For now, LTTngTop will only connect to the first
79live session established on the relay, but in a near future, the user will be able
80to choose which session to attach to.
81
82The default mode after attaching to a session is to start reading the trace from
83this point in time. In order to read the trace from the beginning, the user can specify
84the -b option.
85
85d37ab2
JD
86.SH "KEY BINDINGS"
87
88.TP 7
89\ \ \'\fBF2\fR\': \fICPUTop \fR
90Switch to the CPUTop view which displays the CPU usage of each process
91.TP 7
92\ \ \'\fBF3\fR\': \fIPerfTop \fR
93Switch to the PerfTop view which displays the performance counters (PMU) value of each process (if enabled during tracing)
94.TP 7
95\ \ \'\fBF4\fR\': \fIIOTop \fR
96Switch to the IOTop view which displays the I/O usage of each process (as of now read and writes on any file descriptor network or disk)
97.TP 7
98\ \ \'\fBEnter\fR\': \fIProcess details \fR
99Display all relevant information for the process selected
100.TP 7
101\ \ \'\fBSpace\fR\': \fIHighlight \fR
102Highlights the process under the blue line to make it easy to find it across all views or toggle view in preference panel\fR
103.TP 7
104\ \ \'\fBq\fR\': \fIQuit \fR
105Exit the program
106.TP 7
e15ed00a
JD
107\ \ \'\fBt\fR\': \fIThreads \fR
108Toggle threads display in CPUTop
109.TP 7
85d37ab2
JD
110\ \ \'\fBr\fR\': \fIPreferences \fR
111Display the preference menu for the current view, this menu helps select the column displayed (only in PerfTop view for now) and the column to sort, use 's' to sort and 'space' to toggle the view
112.TP 7
113\ \ \'\fBs\fR\': \fISort \fR
114In preference view, sort on the currently selected line
115.TP 7
116\ \ \'\fBp\fR\': \fIPause/Resume \fR
117Pause the display, hit again to resume the refresh (only works when the trace has not been fully displayed)
118.TP 7
119\ \ \'\fBRight arrow\fR\': \fIMove forward in time \fR
120Display the next second of data, can be hit several time to bypass the default 1 second refresh period to fast forward
121.TP 7
122\ \ \'\fBLeft arrow\fR\': \fIMove backward in time \fR
123Display the previous second of data, automatically switch to pause if not already enabled
124.TP 7
125\ \ \'\fBUp arrow\' / \'k\'\fR: \fIMove UP the cursor \fR
126Move up the blue line to select processes \fR
127.TP 7
128\ \ \'\fBDown arrow\' / \'j\'\fR: \fIMove DOWN the cursor \fR
129Move down the blue line to select processes
41ff0645
JD
130.TP 7
131\ \ \'\fB>\fR': \fI Sort the next column \fR
132Update the sorting to the next column
133.TP 7
134\ \ \'\fB<\fR': \fI Sort the previous column \fR
135Update the sorting to the previous column
85d37ab2 136
661ad2e0
JD
137.SH "SEE ALSO"
138
139.PP
140babeltrace(1), babeltrace-log(1), lttng(1), lttng-ust(3), lttng-sessiond(8)
141.PP
142.SH "BUGS"
143
144.PP
54645d5c
JD
145The I/O history has some problems with the file names, and we are missing some
146system calls parsing to have the complete I/O accounting.
661ad2e0
JD
147
148If you encounter any issues or usability problem, please report it on
149our mailing list <lttng-dev@lists.lttng.org> to help improve this
150project.
151.SH "CREDITS"
152
153LTTngTop is distributed under the GPLv2 license. See the LICENSE file
154in the source tree for details.
155
156.PP
157A Web site is available at http://www.efficios.com/babeltrace for more
158information on Babeltrace and the Common Trace Format. See
159http://lttng.org for more information on the LTTng project.
160.PP
161Mailing list for support and development: <lttng-dev@lists.lttng.org>.
162.PP
163You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
164.PP
165
166.SH "AUTHORS"
167
168.PP
169LTTngTop was originally written by Julien Desfossez, with contribution
170from Mathieu Bain for the I/O bandwidth view, and suggestions and ideas
171from the team working with the LTTng project. It is currently
172maintained by Julien Desfossez <jdesfossez@efficios.com>
173.PP
This page took 0.044697 seconds and 4 git commands to generate.