LTTNGTOP(1)                                                      LTTNGTOP(1)

NAME         top

       lttngtop — LTTng Trace Viewer

SYNOPSIS         top

       lttngtop INPUT

DESCRIPTION         top

       Lttngtop is a ncurses interface for reading and browsing traces
       recorded by the LTTng tracer and displaying various statistics. As of
       now, the cpu usage, performance counters and per process/file I/O
       bandwidth are displayed. This version currently only supports offline
       traces, but a live version is in alpha and will be available for
       testing soon.

OPTIONS         top

       INPUT  Input trace path


       LTTngTop requires that the pid, procname, tid and ppid context
       information are enabled during tracing.

       The command --create-local-session does all the required setup for a
       local trace (that must be stopped and destroyed manually by the
       user).  And the command --create-live-session does all the required
       setup for a live trace on localhost (it must also be stopped and
       destroyed manually by the user).

       If you want the CPU activity view, you need the sched_switch event,
       if you want the I/O statistics, you need to enable the system call
       tracing, and if you want the performance counters, you need to enable
       them for the events you are interested in (or all of them). Note,
       there is a hardware limitation for the number of performance counter
       you can enable, check dmesg for information.

       The following example creates a trace with all events enabled, the
       mandatory context informations and three performance counters. It
       assumes that you are running as root or with a user part of the
       tracing group and a lttng-sessiond launched as root.

       lttng create lttngtop
       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
       lttng enable-event -k --syscall -a -s lttngtop
       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
       lttng start lttngtop
       sleep 10
       lttng stop lttngtop
       lttng destroy lttngtop

LIVE STREAMING         top

       In addition to offline traces, LTTngTop can read traces while they
       are being recorded. The official supported way of doing live
       streaming is using lttng-tools >=2.4 and following the documentation
       in live-reading-howto.txt of lttng-tools and README-LIVE of lttngtop.
       An other experimental way of doing live tracing is with mmap, but
       this requires some more work because is not officially supported and
       requires out-of-tree patches to lttng-tools and babeltrace.

       To use the network live-reading, the user only needs to specify the
       relayd hostname or IP address with the option -r. For now, LTTngTop
       will only connect to the first live session established on the relay,
       but in a near future, the user will be able to choose which session
       to attach to.

       The default mode after attaching to a session is to start reading the
       trace from this point in time. In order to read the trace from the
       beginning, the user can specify the -b option.

KEY BINDINGS         top

         ´F2´: CPUTop
              Switch to the CPUTop view which displays the CPU usage of each

         ´F3´: PerfTop
              Switch to the PerfTop view which displays the performance
              counters (PMU) value of each process (if enabled during

         ´F4´: IOTop
              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)

         ´Enter´: Process details
              Display all relevant information for the process selected

         ´Space´: Highlight
              Highlights the process under the blue line to make it easy to
              find it across all views or toggle view in preference panel

         ´q´: Quit
              Exit the program

         ´t´: Threads
              Toggle threads display in CPUTop

         ´r´: Preferences
              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

         ´s´: Sort
              In preference view, sort on the currently selected line

         ´p´: Pause/Resume
              Pause the display, hit again to resume the refresh (only works
              when the trace has not been fully displayed)

         ´Right arrow´: Move forward in time
              Display the next second of data, can be hit several time to
              bypass the default 1 second refresh period to fast forward

         ´Left arrow´: Move backward in time
              Display the previous second of data, automatically switch to
              pause if not already enabled

         ´Up arrow´ / ´k´: Move UP the cursor
              Move up the blue line to select processes

         ´Down arrow´ / ´j´: Move DOWN the cursor
              Move down the blue line to select processes

         ´>':  Sort the next column
              Update the sorting to the next column

         ´<':  Sort the previous column
              Update the sorting to the previous column

SEE ALSO         top

       babeltrace(1), babeltrace-log(1), lttng(1), lttng-ust(3), lttng-

BUGS         top

       The I/O history has some problems with the file names, and we are
       missing some system calls parsing to have the complete I/O

       If you encounter any issues or usability problem, please report it on
       our mailing list <> to help improve this

CREDITS         top

       LTTngTop is distributed under the GPLv2 license. See the LICENSE file
       in the source tree for details.

       A Web site is available at for
       more information on Babeltrace and the Common Trace Format. See for more information on the LTTng project.

       Mailing list for support and development: <lttng->.

       You can find us on IRC server (OFTC) in #lttng.

AUTHORS         top

       LTTngTop was originally written by Julien Desfossez, with
       contribution from Mathieu Bain for the I/O bandwidth view, and
       suggestions and ideas from the team working with the LTTng project.
       It is currently maintained by Julien Desfossez

COLOPHON         top

       This page is part of the lttngtop (    LTTng top-like application)
       project.  Information about the project can be found at 
       ⟨⟩.  It is not known how to report bugs for this man
       page; if you know, please send a mail to  This
       page was obtained from the project's upstream Git repository ⟨git⟩ on
       2017-03-13.  If you discover any rendering problems in this HTML ver‐
       sion of the page, or you believe there is a better or more up-to-date
       source for the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original man‐
       ual page), send a mail to

                                June 01, 2015                    LTTNGTOP(1)