doc/lttngtop.1

   1 .TH "LTTNGTOP" "1" "April 18, 2012" "" ""
   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 No knows bugs at this point.
 146
 147 If you encounter any issues or usability problem, please report it on
 148 our mailing list <lttng-dev@lists.lttng.org> to help improve this
 149 project.
 150 .SH "CREDITS"
 151
 152 LTTngTop is distributed under the GPLv2 license. See the LICENSE file
 153 in the source tree for details.
 154
 155 .PP
 156 A Web site is available at http://www.efficios.com/babeltrace for more
 157 information on Babeltrace and the Common Trace Format. See
 158 http://lttng.org for more information on the LTTng project.
 159 .PP
 160 Mailing list for support and development: <lttng-dev@lists.lttng.org>.
 161 .PP
 162 You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
 163 .PP
 164
 165 .SH "AUTHORS"
 166
 167 .PP
 168 LTTngTop was originally written by Julien Desfossez, with contribution
 169 from Mathieu Bain for the I/O bandwidth view, and suggestions and ideas
 170 from the team working with the LTTng project. It is currently
 171 maintained by Julien Desfossez <jdesfossez@efficios.com>
 172 .PP