lttngtrace man page

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>

diff --git a/doc/lttngtrace.1 b/doc/lttngtrace.1
new file mode 100644 (file)
index 0000000..e14218c
--- /dev/null
+++ b/doc/lttngtrace.1
@@ -0,0 +1,108 @@
+.TH "LTTNGTRACE" "1" "June 01, 2015" "" ""
+
+.SH "NAME"
+lttngtrace \(em Live textual LTTng Trace Viewer
+
+.SH "SYNOPSIS"
+
+.PP
+.nf
+lttngtrace [OPTIONS] [EXECUTABLE]
+.fi
+.SH "DESCRIPTION"
+
+.PP
+
+Lttngtrace 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"
+
+lttngtrace 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