fix: don't return an error if a directory does not contain a valid trace
[lttngtop.git] / doc / lttngtop.1
CommitLineData
661ad2e0
JD
1.TH "LTTNGTOP" "1" "April 18, 2012" "" ""
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.
33.PP
34
35.PP
36If you want the CPU activity view, you need the sched_switch event, if you
37want the I/O statistics, you need to enable the system call tracing, and if
38you want the performance counters, you need to enable them for the events you
39are interested in (or all of them). Note, there is a hardware limitation for the
40number of performance counter you can enable, check dmesg for information.
41.PP
42
43.PP
44The following example creates a trace with all events enabled, the mandatory context informations and
45three performance counters. It assumes that you are running as root or with a user part of the tracing group and a lttng-sessiond
46launched as root.
47.PP
48
49.nf
50lttng create lttngtop
51lttng enable-event -k -a
52lttng add-context -k -t pid -t procname -t tid -t ppid -t perf:cache-misses -t perf:major-faults -t perf:branch-load-misses
53lttng start
54sleep 10
55lttng stop
56lttng destroy
57.fi
58
85d37ab2
JD
59.SH "KEY BINDINGS"
60
61.TP 7
62\ \ \'\fBF2\fR\': \fICPUTop \fR
63Switch to the CPUTop view which displays the CPU usage of each process
64.TP 7
65\ \ \'\fBF3\fR\': \fIPerfTop \fR
66Switch to the PerfTop view which displays the performance counters (PMU) value of each process (if enabled during tracing)
67.TP 7
68\ \ \'\fBF4\fR\': \fIIOTop \fR
69Switch 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)
70.TP 7
71\ \ \'\fBEnter\fR\': \fIProcess details \fR
72Display all relevant information for the process selected
73.TP 7
74\ \ \'\fBSpace\fR\': \fIHighlight \fR
75Highlights the process under the blue line to make it easy to find it across all views or toggle view in preference panel\fR
76.TP 7
77\ \ \'\fBq\fR\': \fIQuit \fR
78Exit the program
79.TP 7
e15ed00a
JD
80\ \ \'\fBt\fR\': \fIThreads \fR
81Toggle threads display in CPUTop
82.TP 7
85d37ab2
JD
83\ \ \'\fBr\fR\': \fIPreferences \fR
84Display 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
85.TP 7
86\ \ \'\fBs\fR\': \fISort \fR
87In preference view, sort on the currently selected line
88.TP 7
89\ \ \'\fBp\fR\': \fIPause/Resume \fR
90Pause the display, hit again to resume the refresh (only works when the trace has not been fully displayed)
91.TP 7
92\ \ \'\fBRight arrow\fR\': \fIMove forward in time \fR
93Display the next second of data, can be hit several time to bypass the default 1 second refresh period to fast forward
94.TP 7
95\ \ \'\fBLeft arrow\fR\': \fIMove backward in time \fR
96Display the previous second of data, automatically switch to pause if not already enabled
97.TP 7
98\ \ \'\fBUp arrow\' / \'k\'\fR: \fIMove UP the cursor \fR
99Move up the blue line to select processes \fR
100.TP 7
101\ \ \'\fBDown arrow\' / \'j\'\fR: \fIMove DOWN the cursor \fR
102Move down the blue line to select processes
41ff0645
JD
103.TP 7
104\ \ \'\fB>\fR': \fI Sort the next column \fR
105Update the sorting to the next column
106.TP 7
107\ \ \'\fB<\fR': \fI Sort the previous column \fR
108Update the sorting to the previous column
85d37ab2 109
661ad2e0
JD
110.SH "SEE ALSO"
111
112.PP
113babeltrace(1), babeltrace-log(1), lttng(1), lttng-ust(3), lttng-sessiond(8)
114.PP
115.SH "BUGS"
116
117.PP
118No knows bugs at this point.
119
120If you encounter any issues or usability problem, please report it on
121our mailing list <lttng-dev@lists.lttng.org> to help improve this
122project.
123.SH "CREDITS"
124
125LTTngTop is distributed under the GPLv2 license. See the LICENSE file
126in the source tree for details.
127
128.PP
129A Web site is available at http://www.efficios.com/babeltrace for more
130information on Babeltrace and the Common Trace Format. See
131http://lttng.org for more information on the LTTng project.
132.PP
133Mailing list for support and development: <lttng-dev@lists.lttng.org>.
134.PP
135You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
136.PP
137
138.SH "AUTHORS"
139
140.PP
141LTTngTop was originally written by Julien Desfossez, with contribution
142from Mathieu Bain for the I/O bandwidth view, and suggestions and ideas
143from the team working with the LTTng project. It is currently
144maintained by Julien Desfossez <jdesfossez@efficios.com>
145.PP
This page took 0.027093 seconds and 4 git commands to generate.