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