Update and add to the quickstart guide

Signed-off-by: David Goulet <david.goulet@polymtl.ca>

diff --git a/doc/quickstart.txt b/doc/quickstart.txt
index d3fde8666bcace092fff082bec67c11f1ec7b6f5..a979f5bfe8b00f8195aaf4e793b17a77eb9e19fe 100644 (file)
--- a/doc/quickstart.txt
+++ b/doc/quickstart.txt
@@ -1,24 +1,35 @@
+NOTES:
+--------------
+2011-07-21 : User-space tracer is not released. Tracing in user-space at this
+point is not possible with lttng-tools.
+
 QUICKSTART
 --------------
 
 This is a quick start guide for the complete LTTng tool chain. This is divided
-in three sections respectively Kernel tracing, user-space tracing and reading a
+in three sections respectively kernel tracing, user-space tracing and reading a
 trace.
 
 See the README file for installation procedure or use the various Linux
 distribution packages.
 
-In order to trace the Kernel, you'll need the lttng-modules >= 2.0 compiled and
-installed. See http://lttng.org/content/lttng-kernel-tracer for more
-instructions for that part. For user-space tracing, you'll need an instrumented
-application, please see http://lttng.org/ust
+In order to trace the kernel, you'll need the lttng-modules >= 2.0 compiled and
+installed. See http://lttng.org/lttng2.0 for more instructions for that part.
+For user-space tracing, you'll need an instrumented application, please see
+http://lttng.org/ust.
 
 lttng-tools provide a session daemon (ltt-sessiond) that acts as a tracing
 registry. To trace any instrumented applications or the kernel, a registered
-tracing session is needed.
+tracing session is needed beforehand. To interact with the session daemon and a
+tracing session, you should use the lttng command line UI (lttng).
 
-To interact with the session daemon and a tracing session, you can use the
-lttng command line UI (lttng).
+Here is a list of some new powerful features the LTTng 2.0 kernel tracer
+offers:
+
+       * Kprobes support
+       * Function Tracer support
+       * Context information support (add context data to an event)
+       * Perf counter support
 
 The next sections explain how to do tracing :)
 
@@ -26,10 +37,10 @@ Kernel Tracing
 --------------
 
 You have to modprobe the lttng-modules manually or the session daemon will do
-it for you if they can be found on your system.
+it for you if those modules can be found on your system.
 
-You can then start the session daemon by hand or the lttng command line tool
-will do it for you.
+Again, you can then start the session daemon (ltt-sessiond) by hand or the
+lttng command line tool will do it for you.
 
 List possible kernel events:
 
@@ -40,6 +51,10 @@ the session name (here 'mysession') you are working on.
 
 # lttng create mysession
 
+If you have multiple sessions, you can change the current session by using
+
+# lttng set-session myothersession
+
 2) Enable event(s). Here for example, we want only 'sched_switch' and
 'sys_enter' events for the kernel (-k/--kernel).
 
@@ -49,21 +64,69 @@ or enable ALL events (-a/--all):
 
 # lttng enable-event -a -k
 
-3) Start tracing:
+3) Enable kprobes and/or the function tracer with lttng
+
+This is a new feature made possible by the new LTTng 2.0 kernel tracer. You can
+enable a Kprobe (by Masami Hiramatsu) and data will be output in the trace
+along side with your tracing data.
+
+# lttng enable-event aname --kprobe symbol+0xffff7260695
+
+or
+
+# lttng enable-event aname --kprobe 0xffff7260695
+
+Either an <address> or a <symbol+offset> can be used for kprobes.
+
+You can also enable function tracer, which uses the ftrace API (by Steven
+Rostedt). Again, data will be output in the trace.
+
+# lttng enable-event aname --function <symbol_name>
+
+4) Enable context information for an event:
+
+This is also a new feature which allows you to add context information to an
+event. For example, you can add the PID along with the event information:
+
+# lttng add-context -k -e sched_switch -t 0
+
+At this point, you will have to look at 'lttng add-context --help' for all
+possible context type which are integer values.
+
+You can on the same line activate multiple context:
+
+# lttng add-context -k -e sched_switch -t 0 -t 2 -t 4
+
+5) Enable perf counter for an event:
+
+Again, a new powerful feature is the possibility to add perf counter data
+(using the perf API by Ingo Molnar) to the trace on a per event basis. Let say
+we want to get the CPU cycles at each define event:
+
+# lttng add-context -k -e sched_switch --perf-name aname --perf-type 0 --perf-id 0
+
+You'll have to use the add-context help for all possible perf counter values.
+
+6) Start tracing:
 
 # lttng start
 
-Tracing is in progress at this point and will be written in
+Tracing is in progress at this point and traces will be written in
 $HOME/lttng-traces/mysession-<date>-<time>
 
-4) Stop tracing:
+7) Stop tracing:
 
 # lttng stop
 
-5) Destroy your session after you are done with tracing
+Note: At this point, you can restart the trace (lttng start), enable/disable
+events or just go take a break and come back 3 days later to start it again :).
+
+8) Destroy your session after you are done with tracing
 
 # lttng destroy
 
+See Reading a trace section below to read you trace(s).
+
 User-space Tracing
 --------------
 
@@ -80,3 +143,7 @@ http://git.efficios.com/?p=babeltrace.git
 # babeltrace -n $HOME/lttng-traces/mysession-<date>-<time> | less
 
 Voilà!
+
+Please report any bugs/comments on our mailing list
+(ltt-dev@lists.casi.polymtl.ca) or you can go on our IRC channel at
+irc.oftc.net, channel #lttng