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 .PP
  34
  35 .PP
  36 If you want the CPU activity view, you need the sched_switch event, if you
  37 want the I/O statistics, you need to enable the system call tracing, and if
  38 you want the performance counters, you need to enable them for the events you
  39 are interested in (or all of them). Note, there is a hardware limitation for the
  40 number of performance counter you can enable, check dmesg for information.
  41 .PP
  42
  43 .PP
  44 The following example creates a trace with all events enabled, the mandatory context informations and
  45 three performance counters. It assumes that you are running as root or with a user part of the tracing group and a lttng-sessiond
  46 launched as root.
  47 .PP
  48
  49 .nf
  50 lttng create lttngtop
  51 lttng enable-event -k -a
  52 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
  53 lttng start
  54 sleep 10
  55 lttng stop
  56 lttng destroy
  57 .fi
  58
  59 .SH "KEY BINDINGS"
  60
  61 .TP 7
  62 \ \ \'\fBF2\fR\': \fICPUTop \fR
  63 Switch to the CPUTop view which displays the CPU usage of each process
  64 .TP 7
  65 \ \ \'\fBF3\fR\': \fIPerfTop \fR
  66 Switch 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
  69 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)
  70 .TP 7
  71 \ \ \'\fBEnter\fR\': \fIProcess details \fR
  72 Display all relevant information for the process selected
  73 .TP 7
  74 \ \ \'\fBSpace\fR\': \fIHighlight \fR
  75 Highlights 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
  78 Exit the program
  79 .TP 7
  80 \ \ \'\fBt\fR\': \fIThreads \fR
  81 Toggle threads display in CPUTop
  82 .TP 7
  83 \ \ \'\fBr\fR\': \fIPreferences \fR
  84 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
  85 .TP 7
  86 \ \ \'\fBs\fR\': \fISort \fR
  87 In preference view, sort on the currently selected line
  88 .TP 7
  89 \ \ \'\fBp\fR\': \fIPause/Resume \fR
  90 Pause 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
  93 Display 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
  96 Display 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
  99 Move up the blue line to select processes \fR
 100 .TP 7
 101 \ \ \'\fBDown arrow\' / \'j\'\fR: \fIMove DOWN the cursor \fR
 102 Move down the blue line to select processes
 103
 104 .SH "SEE ALSO"
 105
 106 .PP
 107 babeltrace(1), babeltrace-log(1), lttng(1), lttng-ust(3), lttng-sessiond(8)
 108 .PP
 109 .SH "BUGS"
 110
 111 .PP
 112 No knows bugs at this point.
 113
 114 If you encounter any issues or usability problem, please report it on
 115 our mailing list <lttng-dev@lists.lttng.org> to help improve this
 116 project.
 117 .SH "CREDITS"
 118
 119 LTTngTop is distributed under the GPLv2 license. See the LICENSE file
 120 in the source tree for details.
 121
 122 .PP
 123 A Web site is available at http://www.efficios.com/babeltrace for more
 124 information on Babeltrace and the Common Trace Format. See
 125 http://lttng.org for more information on the LTTng project.
 126 .PP
 127 Mailing list for support and development: <lttng-dev@lists.lttng.org>.
 128 .PP
 129 You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
 130 .PP
 131
 132 .SH "AUTHORS"
 133
 134 .PP
 135 LTTngTop was originally written by Julien Desfossez, with contribution
 136 from Mathieu Bain for the I/O bandwidth view, and suggestions and ideas
 137 from the team working with the LTTng project. It is currently
 138 maintained by Julien Desfossez <jdesfossez@efficios.com>
 139 .PP