Update documentation following babeltrace UI change

[lttng-tools.git] / doc / quickstart.txt

diff --git a/doc/quickstart.txt b/doc/quickstart.txt
index 1234fea6dc29006e31b525f01435d419e51e4a99..be43d49dfce88362acd145a550ce82677c0ad8ef 100644 (file)
--- a/doc/quickstart.txt
+++ b/doc/quickstart.txt
@@ -23,26 +23,26 @@ registry. To trace any instrumented applications or the kernel, a registered
 tracing session is needed beforehand. To interact with the session daemon and a
 tracing session, you should use the lttng command line UI (lttng).
 
 tracing session is needed beforehand. To interact with the session daemon and a
 tracing session, you should use the lttng command line UI (lttng).
 

-Here is a list of some new powerful features the LTTng 2.0 kernel tracer
-offers:
+Here is a list of some 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
 
        * Kprobes support
        * Function Tracer support
        * Context information support (add context data to an event)
        * Perf counter support

+       * Tracepoint support

 
 The next sections explain how to do tracing :)
 
 Kernel Tracing
 --------------
 
 
 The next sections explain how to do tracing :)
 
 Kernel Tracing
 --------------
 

-You have to modprobe the lttng-modules manually or the session daemon will do
-it for you if those modules can be found on your system.
+You can start the session daemon by invoking the command "ltt-sessiond",
+or let the lttng command line tool do it for you. The session daemon
+loads the LTTng tracer modules for you if those modules can be found on
+your system. If they are not found, the kernel tracing feature will be
+unavailable.

 
 

-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:
+List available kernel events:

 
 # lttng list -k
 
 
 # lttng list -k
 


@@ -55,73 +55,81 @@ If you have multiple sessions, you can change the current session by using
 
 # lttng set-session myothersession
 
 
 # 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).
+2) Enable all tracepoints and all system call events.
+
+# lttng enable-event -a -k

 
 

-# lttng enable-event sched_switch,sys_enter -k
+3) Enable tracepoint event(s). Here for example, we want only
+'sched_switch' and 'sched_wakeup' events for the kernel (-k/--kernel).

 
 

-or enable ALL events (-a/--all):
+# lttng enable-event sched_switch,sched_wakeup -k

 
 

-# lttng enable-event -a -k
+or enable ALL tracepoint events:
+
+# lttng enable-event -a -k --tracepoint
+
+4) Enable all system call event(s).
+
+# lttng enable-event -a -k --syscall

 
 

-3) Enable kprobes and/or the function tracer with lttng
+5) 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
 
 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.
+enable a dynamic probe and data will be output in the trace along side with
+your tracing data.

 
 

-# lttng enable-event aname --kprobe symbol+0xffff7260695
+# lttng enable-event aname -k --probe symbol+0x0

 
 or
 
 
 or
 

-# lttng enable-event aname --kprobe 0xffff7260695
+# lttng enable-event aname -k --probe 0xffff7260695

 
 

-Either an <address> or a <symbol+offset> can be used for kprobes.
+Either an <address> or a <symbol+offset> can be used for probes.

 
 

-You can also enable function tracer, which uses the ftrace API (by Steven
+You can also enable function tracer, which uses the Ftrace API (by Steven

 Rostedt). Again, data will be output in the trace.
 
 Rostedt). Again, data will be output in the trace.
 

-# lttng enable-event aname --function <symbol_name>
+# lttng enable-event aname -k --function <symbol_name>

 
 

-4) Enable context information for an event:
+6) 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:
 
 
 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
+# lttng add-context -k -e sched_switch -t pid

 
 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:
 
 
 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
+# lttng add-context -k -e sched_switch -t pid -t nice -t tid

 
 

-5) Enable perf counter for an event:
+7) Enable perf counter for an event:

 
 Again, a new powerful feature is the possibility to add perf counter data
 
 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:
+(using the perf API by Ingo Molnar and Thomas Gleixner) to the trace on a per
+event basis. Let say we want to get the CPU cycles at each event:

 
 

-# lttng add-context -k -e sched_switch -t 1 --perf-name aname --perf-type 0 --perf-id 0
+# lttng add-context -k -e sched_switch -t perf:cpu-cycles

 
 You'll have to use the add-context help for all possible perf counter values.
 
 
 You'll have to use the add-context help for all possible perf counter values.
 

-6) Start tracing:
+8) Start tracing:

 
 # lttng start
 
 Tracing is in progress at this point and traces will be written in
 $HOME/lttng-traces/mysession-<date>-<time>
 
 
 # lttng start
 
 Tracing is in progress at this point and traces will be written in
 $HOME/lttng-traces/mysession-<date>-<time>
 

-7) Stop tracing:
+9) Stop tracing:

 
 # lttng stop
 
 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 :).
 
 
 # lttng stop
 
 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
+10) Destroy your session after you are done with tracing

 
 # lttng destroy
 
 
 # lttng destroy
 


@@ -136,11 +144,12 @@ you need to use 'ustctl' to control user-space tracing.
 Reading a trace
 --------------
 
 Reading a trace
 --------------
 

-To read your trace, you can use babeltrace which will text dump your the
-trace. Please see http://www.efficios.com/ctf and git tree
+The tool "Babeltrace" can be used to dump your binary trace into a
+human-readable text format. Please see
+http://www.efficios.com/babeltrace and git tree

 http://git.efficios.com/?p=babeltrace.git
 
 http://git.efficios.com/?p=babeltrace.git
 

-# babeltrace -n $HOME/lttng-traces/mysession-<date>-<time> | less
+# babeltrace $HOME/lttng-traces/mysession-<date>-<time> | less

 
 Voilà!
 
 
 Voilà!