From 6f8eb30473ece47ca4bad68d3f4da2ea7a63e6a4 Mon Sep 17 00:00:00 2001 From: David Goulet Date: Thu, 21 Jul 2011 10:47:55 -0400 Subject: [PATCH] Update and add to the quickstart guide Signed-off-by: David Goulet --- doc/quickstart.txt | 97 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 82 insertions(+), 15 deletions(-) diff --git a/doc/quickstart.txt b/doc/quickstart.txt index d3fde8666..a979f5bfe 100644 --- 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
or a 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 + +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--