X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;f=doc%2Fquickstart.txt;h=06b308406c0a7134655a02bb46b3d09f2b492aa6;hb=04938faeeb4b28c5791029a2542848534ac83b17;hp=e5e1f170565de2408d48b068824e76ce1926324e;hpb=e765105490394ee9f663c7c25d343b9146a023da;p=lttng-tools.git diff --git a/doc/quickstart.txt b/doc/quickstart.txt index e5e1f1705..06b308406 100644 --- a/doc/quickstart.txt +++ b/doc/quickstart.txt @@ -1,82 +1,241 @@ +NOTES: +-------------- + +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 recording session you are working +on. + 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 +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/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 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. +recording session is needed beforehand. To interact with the session daemon and a +recording 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: -To interact with the session daemon and a tracing session, you can use the -lttng command line UI (lttng). + * 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 :) +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 have to modprobe the lttng-modules manually or the session daemon will do -it for you if they 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. -You can then start the session daemon 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 recording 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 -2) Enable event(s). Here for example, we want only 'sched_switch' and -'sys_enter' events for the kernel (-k/--kernel). +If you have multiple sessions, you can change the current session by using -# lttng enable-event sched_switch,sys_enter -k +# lttng set-session myothersession -or enable ALL events (-a/--all): +2) Enable all tracepoints and all system call events. # lttng enable-event -a -k -3) Start tracing: +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 sched_switch,sched_wakeup -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 + +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 dynamic probe and data will be output in the trace along side with +your tracing data. + +# lttng enable-event aname -k --probe symbol+0x0 + +or + +# lttng enable-event aname -k --probe 0xffff7260695 + +Either an
or a