Convert `README.md` to `README.adoc`

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

diff --git a/doc/quickstart.txt b/doc/quickstart.txt
index a979f5bfe8b00f8195aaf4e793b17a77eb9e19fe..9bcb8460469505f8834b86cce940111ca8bd0aa2 100644 (file)
--- a/doc/quickstart.txt
+++ b/doc/quickstart.txt
@@ -1,7 +1,10 @@
 NOTES:
 --------------
 NOTES:
 --------------

-2011-07-21 : User-space tracer is not released. Tracing in user-space at this
-point is not possible with lttng-tools.
+
+2011-12-12: For user-space tracing, only the global UST domain ("-u" alone) is
+supported meaning that if you enable a tracepoint for user-space it will be
+enabled for all applications for the current tracing session you are working
+on.

 
 QUICKSTART
 --------------
 
 QUICKSTART
 --------------


@@ -10,44 +13,53 @@ 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
 trace.
 
 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
+See the README.adoc file for installation procedure or use the various Linux

 distribution packages.
 
 distribution packages.
 

-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.
+In order to trace the kernel, you'll need the lttng-modules 2.0 compiled and
+installed. See https://lttng.org/lttng2.0 for more instructions for that part.
+For user-space tracing, you'll need an instrumented application with lttng-ust
+2.0.

 
 

-lttng-tools provide a session daemon (ltt-sessiond) that acts as a tracing
+lttng-tools provide a session daemon (lttng-sessiond) that acts as a tracing

 registry. To trace any instrumented applications or the kernel, a registered
 tracing session is needed beforehand. To interact with the session daemon and a
 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, you should use the lttng command line UI (lttng). It is also
+possible to use the liblttngctl library for tracing control (lttng.h).

 
 

-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
+
+And for the LTTng UST 2.0 tracer:
+
+       * Applications registration
+       * Automatic tracepoints activation upon app. registration
+       * Context information support
+       * Safe buffers after application crash
+       * Per-user tracing (root access *not* mandatory)

 
 

-The next sections explain how to do tracing :)
+The next sections explains how to do tracing :)

 
 Kernel 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 "lttng-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
 

-1) Create a tracing session. A .lttngrc will be created in $HOME containing
-the session name (here 'mysession') you are working on.
+1) Create a tracing session. The .lttng directory will be created with .lttngrc
+file in $HOME containing the session name (here 'mysession') you are working
+on.

 
 # lttng create mysession
 
 
 # lttng create mysession
 


@@ -55,73 +67,84 @@ 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 sched_switch,sys_enter -k
+# lttng enable-event -a -k

 
 

-or enable ALL events (-a/--all):
+3) Enable tracepoint event(s). Here for example, we want only
+'sched_switch' and 'sched_wakeup' events for the kernel (-k/--kernel).

 
 

-# lttng enable-event -a -k
+# lttng enable-event sched_switch,sched_wakeup -k

 
 

-3) Enable kprobes and/or the function tracer with lttng
+or enable ALL tracepoint events:
+
+# lttng enable-event -a -k --tracepoint
+
+4) Enable all system call event(s).
+
+# lttng enable-event -a -k --syscall
+
+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
 
 At this point, you will have to look at 'lttng add-context --help' for all

-possible context type which are integer values.
+possible context type.

 
 You can on the same line activate multiple context:
 
 
 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 --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:
+NOTE: It will start tracing for *all* domain(s).
+
+9) Stop tracing:

 
 # lttng stop
 
 
 # lttng stop
 

-Note: At this point, you can restart the trace (lttng start), enable/disable
+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 :).
 events or just go take a break and come back 3 days later to start it again :).

+You can also read the trace since the buffers are flushed on stop command.

 
 

-8) Destroy your session after you are done with tracing
+10) Destroy your session after you are done with tracing

 
 # lttng destroy
 
 
 # lttng destroy
 


@@ -130,20 +153,89 @@ See Reading a trace section below to read you trace(s).
 User-space Tracing
 --------------
 
 User-space Tracing
 --------------
 

-User-space tracer 2.0 not released at this point. For the 0.x versions,
-you need to use 'ustctl' to control user-space tracing.
+Like kernel tracing, you can start the session daemon by invoking the command
+"lttng-sessiond", or let the lttng command line tool do it for you.
+
+NOTE: You do *not* need root credentials in order to tracer user-space
+applications. However, if you run the session daemon under non-root user
+rights, only applications of that user will be traced.
+
+So, after instrumenting you applications with LTTng-ust 2.0
+(https://lttng.org/lttng2.0), upon startup, it will automatically register to
+the session daemon. If there is none running, it will simply wait on a seperate
+thread for a session daemon to appear and then register.
+
+Start your instrumented application at any time but at least before starting
+tracing :).
+
+List available registered applications:
+
+$ lttng list -u
+
+1) Create a tracing session. The .lttng directory will be created with a
+.lttngrc file in $HOME containing 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 all tracepoints for the global UST domain ("-u" alone).
+
+$ lttng enable-event -a -u
+
+or enable a single tracepoint event.
+
+$ lttng enable-event ust_tests_hello:tptest -u
+
+3) 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 -t pid -e ust_tests_hello:tptest -u
+
+At this point, you will have to look at 'lttng add-context --help' for all
+possible context type.
+
+You can on the same line activate multiple context:
+
+$ lttng add-context -u -e ust_tests_hello:tptest -t pid -t nice -t tid
+
+4) Start tracing:
+
+$ lttng start
+
+Tracing is in progress at this point and traces will be written in the session
+directory.
+
+NOTE: It will start tracing for *all* domain(s).
+
+5) 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 :).
+You can also read the trace since the buffers are flushed on stop command.
+
+6) Destroy your session after you are done with tracing
+
+$ lttng destroy
+
+See "Reading a trace" section below to read you trace(s).
+

 
 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
-http://git.efficios.com/?p=babeltrace.git
+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

 
 

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

 
 Voilà!
 
 
 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
+Please report any bugs/comments on our mailing list (lttng-dev@lists.lttng.org)
+or you can go on our IRC channel at irc.oftc.net, channel #lttng