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 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/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 beforehand. To interact with the session daemon and a tracing session, you should use the lttng command line UI (lttng). 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 The next sections explain 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. Again, you can then start the session daemon (ltt-sessiond) by hand or the lttng command line tool will do it for you. 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. # 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). # lttng enable-event sched_switch,sys_enter -k or enable ALL events (-a/--all): # lttng enable-event -a -k 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 dynamic probe and data will be output in the trace along side with your tracing data. # lttng enable-event aname --probe symbol+0xffff7260695 or # lttng enable-event aname --probe 0xffff7260695 Either an
or a can be used for probes. 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 pid 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 pid -t nice -t tid 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 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 perf:cpu-cycles 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 traces will be written in $HOME/lttng-traces/mysession--