Add project status to readme

[lttngtop.git] / doc / lttngtoptrace.1

.TH "LTTNGTOPTRACE" "1" "June 01, 2015" "" ""

.SH "NAME"
lttngtoptrace \(em Live textual LTTng Trace Viewer

.SH "SYNOPSIS"

.PP
.nf
lttngtoptrace [OPTIONS] [EXECUTABLE]
.fi
.SH "DESCRIPTION"

.PP

Lttngtoptrace is a live textual LTTng trace viewer, it allows to easily (one
command) start a LTTng session and view the live events. The intent is to do
something similar to strace but less intrusive and more flexible:
.nf
- run a command and see it's kernel trace almost instantly without slowing it
  down too much (buffered at most 1 second) in combination with the trace of
  any other process or the whole system
- follow multiple processes and/or the whole system
- follow the children of all attached processes
- attach to processes by name and/or pid
- actual time taken by the system calls (with reminder of start timestamp)
- sched_switch events to know the context switches that occurred for the
  process we are interested in
- current CPU (to see the migrations)
- highlight the trace of a selection of processes while tracing the whole
  system to easily see the interactions
- arbitrary kprobe additions to see if a process hits a certain place in the
  kernel
.fi

.PP
Only a subset of the LTTng events are enabled (the statedump, sched_switch,
sched_process_fork and all the system calls).

.PP

The events are displayed with additionnal context information than just the raw
LTTng trace (such as the current process name/PID/TID, the start/end time of
the current system call, the delay since the last displayed event (filtering
aware)).

.SH "OPTIONS"

.TP
.BR "-f"
Follow threads associated with selected PIDs
.TP
.BR "-p"
Comma-separated list of PIDs to display (in addition to the eventual executed program)
.TP
.BR "-n"
Comma-separated list of procnames to display (in addition to the eventual executed program)
.TP
.BR "-a"
In textdump mode, display all events but write in bold the processes we are interested in (-f and -p)
.TP
.BR "-k"
kprobes to insert (same format as lttng enable-event, can be repeated)
.TP
.BR "-o <filename>"
In textdump, output the log in <filename>
.TP
.BR "EXECUTABLE"
Program to run and connect the tracer (can be combined with other options to see the trace of other processes)

.SH "REQUIREMENTS"

.PP

A working installation of LTTng >= 2.4, the appropriate rights for the user to
create a kernel trace and start daemons (sudo is tried in case the user is not
root), Babeltrace = 1.2.4, LTTngTop = 0.3

.SH "SEE ALSO"

.PP
lttngtop(1), babeltrace(1), babeltrace-log(1), lttng(1), lttng-ust(3), lttng-sessiond(8)
.PP
.SH "BUGS"

.PP
Some highlighting problems with -a
.SH "CREDITS"

lttngtoptrace is a wrapper on top of LTTngTop released under the GPLv2 license.
See the LICENSE file in the source tree for details.

.PP
A Web site is available at http://www.efficios.com/babeltrace for more
information on Babeltrace and the Common Trace Format. See
http://lttng.org for more information on the LTTng project.
.PP
Mailing list for support and development: <lttng-dev@lists.lttng.org>.
.PP
You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
.PP

.SH "AUTHORS"

.PP
LTTngTop was originally written and is maintained by Julien Desfossez
<jdesfossez@efficios.com>
.PP