X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fquickstart.txt;h=9bcb8460469505f8834b86cce940111ca8bd0aa2;hb=a942557f174ba5a1b71ae5334ee987643eca691c;hp=1234fea6dc29006e31b525f01435d419e51e4a99;hpb=3301e7404d026657c2e466bcdf504b93ddbe58e3;p=lttng-tools.git
diff --git a/doc/quickstart.txt b/doc/quickstart.txt
index 1234fea6d..9bcb84604 100644
--- a/doc/quickstart.txt
+++ b/doc/quickstart.txt
@@ -1,7 +1,10 @@
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
--------------
@@ -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.
-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.
-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
-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
+ * 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
--------------
-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
-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
@@ -55,73 +67,84 @@ 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).
+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
-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
-# lttng enable-event aname --kprobe 0xffff7260695
+# lttng enable-event aname -k --probe 0xffff7260695
-Either an
or a can be used for kprobes.
+Either an or a 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.
-# lttng enable-event aname --function
+# lttng enable-event aname -k --function
-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:
-# 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.
+possible context type.
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
-(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.
-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--