Wiki

This is a quick start guide for the complete LTTng tool chain. This is dividedin three sections respectively kernel tracing, user-space tracing and reading atrace.

See the README file for installation procedure or use the various Linuxdistribution packages.

In order to trace the kernel, you'll need the lttng-modules 2.0 compiled andinstalled. See http://lttng.org/lttng2.0 for more instructions for that part.For user-space tracing, you'll need an instrumented application with lttng-ust2.0.

lttng-tools provide a session daemon (lttng-sessiond) that acts as a tracingregistry. To trace any instrumented applications or the kernel, a registeredtracing session is needed beforehand. To interact with the session daemon and atracing session, you should use the lttng command line UI (lttng). It is alsopossible 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:

You can start the session daemon by invoking the command "lttng-sessiond", orlet the lttng command line tool do it for you. The session daemon loads theLTTng tracer modules for you if those modules can be found on your system. Ifthey are not found, the kernel tracing feature will be unavailable.

List available kernel events:

# lttng list -k

1) Create a tracing session. The .lttng directory will be created with .lttngrcfile in $HOME containing the session name (here 'mysession') you are workingon.

# lttng create mysession

If you have multiple sessions, you can change the current session by using

This is a new feature made possible by the new LTTng 2.0 kernel tracer. You canenable a dynamic probe and data will be output in the trace along side withyour tracing data.

# lttng enable-event aname -k --probe symbol+0x0

or

# lttng enable-event aname -k --probe 0xffff7260695

Either an <address> or a <symbol+offset> can be used for probes.

You can also enable function tracer, which uses the Ftrace API (by StevenRostedt). Again, data will be output in the trace.

# lttng enable-event aname -k --function <symbol_name>

6) Enable context information for an event:

This is also a new feature which allows you to add context information to anevent. 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 allpossible context type.

You can on the same line activate multiple context:

# lttng add-context -k -e sched_switch -t pid -t nice -t tid

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 perevent 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.

8) Start tracing:

# lttng start

Tracing is in progress at this point and traces will be written in$HOME/lttng-traces/mysession-<date>-<time>

NOTE: It will start tracing for all domain(s).

9) Stop tracing:

# lttng stop

NOTE: At this point, you can restart the trace (lttng start), enable/disableevents or just go take a break and come back 3 days later to start it again :).You can also read the trace since the buffers are flushed on stop command.

Like 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.

NOTE: You do not need root credentials in order to tracer user-spaceapplications. However, if you run the session daemon under non-root userrights, only applications of that user will be traced.

So, after instrumenting you applications with LTTng-ust 2.0(http://lttng.org/lttng2.0), upon startup, it will automatically register tothe session daemon. If there is none running, it will simply wait on a seperatethread for a session daemon to appear and then register.

Start your instrumented application at any time but at least before startingtracing :).

List available registered applications:

$ lttng list -u

1) Create a tracing session. The .lttng directory will be created with a.lttngrc file in $HOME containing the session name (here 'mysession') you areworking on.

$ lttng create mysession

If you have multiple sessions, you can change the current session by using:

$ lttng set-session myothersession

2) Enable all tracepoints for the global UST domain ("-u" alone).

$ lttng enable-event -a -u

or enable a single tracepoint event.

$ lttng enable-event ust_tests_hello:tptest -u

3) This is also a new feature which allows you to add context information to anevent. For example, you can add the PID along with the event information:

$ lttng add-context -t pid -e ust_tests_hello:tptest -u

At this point, you will have to look at 'lttng add-context --help' for allpossible context type.

Tracing is in progress at this point and traces will be written in$HOME/lttng-traces/mysession-<date>-<time>/ust/<procname>-<pid>-<date>-<time>

NOTE: It will start tracing for all domain(s).

5) Stop tracing:

$ lttng stop

NOTE: At this point, you can restart the trace (lttng start), enable/disableevents or just go take a break and come back 3 days later to start it again :).You can also read the trace since the buffers are flushed on stop command.