[lttng-modules.git] / README

LTTng 2.x modules

Mathieu Desnoyers
March 29, 2013

LTTng 2.x kernel modules build against a vanilla or distribution kernel, without
need for additional patches. Other features:

- Produces CTF (Common Trace Format) natively,
  (http://www.efficios.com/ctf)
- Tracepoints, Function tracer, CPU Performance Monitoring Unit (PMU)
  counters, kprobes, and kretprobes support,
- Integrated interface for both kernel and userspace tracing,
- Have the ability to attach "context" information to events in the
  trace (e.g. any PMU counter, pid, ppid, tid, comm name, etc).
  All the extra information fields to be collected with events are
  optional, specified on a per-tracing-session basis (except for
  timestamp and event id, which are mandatory).

To build and install, you will need to have your kernel headers available (or
access to your full kernel source tree), and use:

% make
# make modules_install
# depmod -a

If you need to specify the target directory to the kernel you want to build
against, use:

% KERNELDIR=path_to_kernel_dir make
# KERNELDIR=path_to_kernel_dir make modules_install
# depmod -a kernel_version

Use lttng-tools to control the tracer. LTTng tools should automatically load
the kernel modules when needed. Use Babeltrace to print traces as a
human-readable text log. These tools are available at the following URL:
http://lttng.org/lttng2.0

Linux kernels >= 2.6.36 are supported.


* Kernel config options required

CONFIG_MODULES: required
  * Kernel modules support.
CONFIG_KALLSYMS: required
  * See wrapper/ files. This is necessary until the few required missing
    symbols are exported to GPL modules from mainline.
CONFIG_HIGH_RES_TIMERS: required
  * Needed for LTTng 2.0 clock source.
CONFIG_TRACEPOINTS: required
    kernel tracepoint instrumentation
    * Enabled as side-effect of any of the perf/ftrace/blktrace
      instrumentation features.


* Kernel config options supported (optional)

The following kernel configuration options will affect the features
available from LTTng:


CONFIG_HAVE_SYSCALL_TRACEPOINTS:
            system call tracing
               lttng enable-event -k --syscall
               lttng enable-event -k -a
CONFIG_PERF_EVENTS:
            performance counters
               lttng add-context -t perf:*
CONFIG_EVENT_TRACING:
            needed to allow block layer tracing
CONFIG_KPROBES:
            Dynamic probe.
               lttng enable-event -k --probe ...
CONFIG_KRETPROBES:
            Dynamic function entry/return probe.
               lttng enable-event -k --function ...
CONFIG_KALLSYMS_ALL:
            State dump of mapping between block device number and name.


* Note about Perf PMU counters support

Each PMU counter has its zero value set when it is attached to a context with
add-context. Therefore, it is normal that the same counters attached to both the
stream context and event context show different values for a given event; what
matters is that they increment at the same rate.
Commit	Line	Data
	1	LTTng 2.x modules
	2
	3	Mathieu Desnoyers
	4	March 29, 2013
	5
	6	LTTng 2.x kernel modules build against a vanilla or distribution kernel, without
	7	need for additional patches. Other features:
	8
	9	- Produces CTF (Common Trace Format) natively,
	10	(http://www.efficios.com/ctf)
	11	- Tracepoints, Function tracer, CPU Performance Monitoring Unit (PMU)
	12	counters, kprobes, and kretprobes support,
	13	- Integrated interface for both kernel and userspace tracing,
	14	- Have the ability to attach "context" information to events in the
	15	trace (e.g. any PMU counter, pid, ppid, tid, comm name, etc).
	16	All the extra information fields to be collected with events are
	17	optional, specified on a per-tracing-session basis (except for
	18	timestamp and event id, which are mandatory).
	19
	20	To build and install, you will need to have your kernel headers available (or
	21	access to your full kernel source tree), and use:
	22
	23	% make
	24	# make modules_install
	25	# depmod -a
	26
	27	If you need to specify the target directory to the kernel you want to build
	28	against, use:
	29
	30	% KERNELDIR=path_to_kernel_dir make
	31	# KERNELDIR=path_to_kernel_dir make modules_install
	32	# depmod -a kernel_version
	33
	34	Use lttng-tools to control the tracer. LTTng tools should automatically load
	35	the kernel modules when needed. Use Babeltrace to print traces as a
	36	human-readable text log. These tools are available at the following URL:
	37	http://lttng.org/lttng2.0
	38
	39	Linux kernels >= 2.6.36 are supported.
	40
	41
	42	* Kernel config options required
	43
	44	CONFIG_MODULES: required
	45	* Kernel modules support.
	46	CONFIG_KALLSYMS: required
	47	* See wrapper/ files. This is necessary until the few required missing
	48	symbols are exported to GPL modules from mainline.
	49	CONFIG_HIGH_RES_TIMERS: required
	50	* Needed for LTTng 2.0 clock source.
	51	CONFIG_TRACEPOINTS: required
	52	kernel tracepoint instrumentation
	53	* Enabled as side-effect of any of the perf/ftrace/blktrace
	54	instrumentation features.
	55
	56
	57	* Kernel config options supported (optional)
	58
	59	The following kernel configuration options will affect the features
	60	available from LTTng:
	61
	62
	63	CONFIG_HAVE_SYSCALL_TRACEPOINTS:
	64	system call tracing
	65	lttng enable-event -k --syscall
	66	lttng enable-event -k -a
	67	CONFIG_PERF_EVENTS:
	68	performance counters
	69	lttng add-context -t perf:*
	70	CONFIG_EVENT_TRACING:
	71	needed to allow block layer tracing
	72	CONFIG_KPROBES:
	73	Dynamic probe.
	74	lttng enable-event -k --probe ...
	75	CONFIG_KRETPROBES:
	76	Dynamic function entry/return probe.
	77	lttng enable-event -k --function ...
	78	CONFIG_KALLSYMS_ALL:
	79	State dump of mapping between block device number and name.
	80
	81
	82	* Note about Perf PMU counters support
	83
	84	Each PMU counter has its zero value set when it is attached to a context with
	85	add-context. Therefore, it is normal that the same counters attached to both the
	86	stream context and event context show different values for a given event; what
	87	matters is that they increment at the same rate.