X-Git-Url: http://git.efficios.com/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fquickstart.txt;h=018c27b2b939ef7cd075255fd01bcfd8b2b21b1e;hp=64c6ab7718d1bc8a7e82eb87b95125762bf1710e;hb=adf4e918ebd23dd313553f0b11753f8d6b369d9e;hpb=4bc385dd824ca7c10e3177346926350c86d04754 diff --git a/doc/quickstart.txt b/doc/quickstart.txt index 64c6ab771..018c27b2b 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,18 +13,19 @@ 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.md 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 (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 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 "ltt-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 @@ -55,26 +67,30 @@ If you have multiple sessions, you can change the current session by using # lttng set-session myothersession -2) Enable tracepoint event(s). Here for example, we want only +2) Enable all tracepoints and all system call events. + +# lttng enable-event -a -k + +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 (-a/--all): +or enable ALL tracepoint events: -# lttng enable-event -a -k +# lttng enable-event -a -k --tracepoint -3) Enable all system call event(s). +4) Enable all system call event(s). # lttng enable-event -a -k --syscall -4) Enable kprobes and/or the function tracer with lttng +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+0xffff7260695 +# lttng enable-event aname -k --probe symbol+0x0 or @@ -87,7 +103,7 @@ Rostedt). Again, data will be output in the trace. # lttng enable-event aname -k --function -5) 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: @@ -95,13 +111,13 @@ 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: # lttng add-context -k -e sched_switch -t pid -t nice -t tid -6) 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 and Thomas Gleixner) to the trace on a per @@ -111,21 +127,24 @@ event basis. Let say we want to get the CPU cycles at each event: You'll have to use the add-context help for all possible perf counter values. -7) Start tracing: +8) Start tracing: # lttng start Tracing is in progress at this point and traces will be written in $HOME/lttng-traces/mysession--