From 9bb127554f24d6157eba95a22a39df503ad2ea5c Mon Sep 17 00:00:00 2001 From: David Goulet Date: Mon, 12 Dec 2011 14:42:41 -0500 Subject: [PATCH] Update quickstart with UST tracing howto Signed-off-by: David Goulet --- doc/quickstart.txt | 131 ++++++++++++++++++++++++++++++++++++--------- 1 file changed, 107 insertions(+), 24 deletions(-) diff --git a/doc/quickstart.txt b/doc/quickstart.txt index 7078eecc9..f7ec99d37 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 -------------- @@ -13,15 +16,16 @@ 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 +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. +For user-space tracing, you'll need an instrumented application with lttng-ust +2.0. 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 powerful features the LTTng 2.0 kernel tracer offers: @@ -31,23 +35,31 @@ Here is a list of some powerful features the LTTng 2.0 kernel tracer offers: * Perf counter support * Tracepoint support -The next sections explain how to do tracing :) +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 explains how to do tracing :) 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. 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. +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. 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 @@ -99,7 +111,7 @@ event. For example, you can add the PID along with the event information: # 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: @@ -122,12 +134,15 @@ You'll have to use the add-context help for all possible perf counter values. Tracing is in progress at this point and traces will be written in $HOME/lttng-traces/mysession--