[deliverable/lttng-modules.git] / README.md

LTTng-modules
=============

_by [Mathieu Desnoyers](mailto:mathieu.desnoyers@efficios.com)_


LTTng kernel modules are Linux kernel modules which make
[LTTng](http://lttng.org/) kernel tracing possible. They include
essential control modules and many probes which instrument numerous
interesting parts of Linux. LTTng-modules builds against a vanilla or
distribution kernel, with no need for additional patches.

Other notable features:

  - Produces [CTF](http://www.efficios.com/ctf)
    (Common Trace Format) natively.
  - Tracepoints, function tracer, CPU Performance Monitoring Unit (PMU)
    counters, kprobes, and kretprobes support.
  - Have the ability to attach _context_ information to events in the
    trace (e.g., any PMU counter, PID, PPID, TID, command 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).


Building
--------

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

    make
    sudo make modules_install
    sudo depmod -a

The above commands will build LTTng-modules against your
current kernel. If you need to build LTTng-modules against a custom
kernel, do:

    make KERNELDIR=/path/to/custom/kernel
    sudo make KERNELDIR=/path/to/custom/kernel modules_install
    sudo depmod -a kernel_version


### Kernel built-in support

It is also possible to build these modules as part of a kernel image. Simply
run the [`built-in.sh`](built-in.sh) script with the path to your kernel
source directory as an argument.  It will symlink the lttng-modules directory
in the kernel sources and add an include in the kernel Makefile.

Then configure your kernel as usual and enable the `CONFIG_LTTNG` option.


### Required kernel config options

Make sure your target kernel has the following config options enabled:

  - `CONFIG_MODULES`: loadable module support (not strictly required
     when built into the kernel)
  - `CONFIG_KALLSYMS`: see files in [`wrapper`](wrapper); this is
     necessary until the few required missing symbols are exported to GPL
     modules from mainline
  - `CONFIG_HIGH_RES_TIMERS`: needed for LTTng 2.x clock source
  - `CONFIG_TRACEPOINTS`: kernel tracepoint instrumentation
     (enabled as a side-effect of any of the perf/ftrace/blktrace
     instrumentation features)


### Supported (optional) kernel config options

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 probes:

        lttng enable-event -k --probe ...

  - `CONFIG_KRETPROBES`: dynamic function entry/return probes:

        lttng enable-event -k --function ...

  - `CONFIG_KALLSYMS_ALL`: state dump of mapping between block device
    number and name


Usage
-----

Use [LTTng-tools](https://lttng.org/download) to control the tracer.
The session daemon of LTTng-tools should automatically load the LTTng
kernel modules when needed. Use [Babeltrace](https://lttng.org/babeltrace)
to print traces as a human-readable text log.


Support
-------

Linux kernels >= 2.6.36 are supported.


Notes
-----

### 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-modules
	2	=============
	3
	4	_by [Mathieu Desnoyers](mailto:mathieu.desnoyers@efficios.com)_
	5
	6
	7	LTTng kernel modules are Linux kernel modules which make
	8	[LTTng](http://lttng.org/) kernel tracing possible. They include
	9	essential control modules and many probes which instrument numerous
	10	interesting parts of Linux. LTTng-modules builds against a vanilla or
	11	distribution kernel, with no need for additional patches.
	12
	13	Other notable features:
	14
	15	- Produces [CTF](http://www.efficios.com/ctf)
	16	(Common Trace Format) natively.
	17	- Tracepoints, function tracer, CPU Performance Monitoring Unit (PMU)
	18	counters, kprobes, and kretprobes support.
	19	- Have the ability to attach _context_ information to events in the
	20	trace (e.g., any PMU counter, PID, PPID, TID, command name, etc).
	21	All the extra information fields to be collected with events are
	22	optional, specified on a per-tracing-session basis (except for
	23	timestamp and event ID, which are mandatory).
	24
	25
	26	Building
	27	--------
	28
	29	To build and install LTTng-modules, you will need to have your kernel
	30	headers available (or access to your full kernel source tree), and do:
	31
	32	make
	33	sudo make modules_install
	34	sudo depmod -a
	35
	36	The above commands will build LTTng-modules against your
	37	current kernel. If you need to build LTTng-modules against a custom
	38	kernel, do:
	39
	40	make KERNELDIR=/path/to/custom/kernel
	41	sudo make KERNELDIR=/path/to/custom/kernel modules_install
	42	sudo depmod -a kernel_version
	43
	44
	45	### Kernel built-in support
	46
	47	It is also possible to build these modules as part of a kernel image. Simply
	48	run the [`built-in.sh`](built-in.sh) script with the path to your kernel
	49	source directory as an argument. It will symlink the lttng-modules directory
	50	in the kernel sources and add an include in the kernel Makefile.
	51
	52	Then configure your kernel as usual and enable the `CONFIG_LTTNG` option.
	53
	54
	55	### Required kernel config options
	56
	57	Make sure your target kernel has the following config options enabled:
	58
	59	- `CONFIG_MODULES`: loadable module support (not strictly required
	60	when built into the kernel)
	61	- `CONFIG_KALLSYMS`: see files in [`wrapper`](wrapper); this is
	62	necessary until the few required missing symbols are exported to GPL
	63	modules from mainline
	64	- `CONFIG_HIGH_RES_TIMERS`: needed for LTTng 2.x clock source
	65	- `CONFIG_TRACEPOINTS`: kernel tracepoint instrumentation
	66	(enabled as a side-effect of any of the perf/ftrace/blktrace
	67	instrumentation features)
	68
	69
	70	### Supported (optional) kernel config options
	71
	72	The following kernel configuration options will affect the features
	73	available from LTTng:
	74
	75	- `CONFIG_HAVE_SYSCALL_TRACEPOINTS`: system call tracing:
	76
	77	lttng enable-event -k --syscall
	78	lttng enable-event -k -a
	79
	80	- `CONFIG_PERF_EVENTS`: performance counters:
	81
	82	lttng add-context -t perf:*
	83
	84	- `CONFIG_EVENT_TRACING`: needed to allow block layer tracing
	85	- `CONFIG_KPROBES`: dynamic probes:
	86
	87	lttng enable-event -k --probe ...
	88
	89	- `CONFIG_KRETPROBES`: dynamic function entry/return probes:
	90
	91	lttng enable-event -k --function ...
	92
	93	- `CONFIG_KALLSYMS_ALL`: state dump of mapping between block device
	94	number and name
	95
	96
	97	Usage
	98	-----
	99
	100	Use [LTTng-tools](https://lttng.org/download) to control the tracer.
	101	The session daemon of LTTng-tools should automatically load the LTTng
	102	kernel modules when needed. Use [Babeltrace](https://lttng.org/babeltrace)
	103	to print traces as a human-readable text log.
	104
	105
	106	Support
	107	-------
	108
	109	Linux kernels >= 2.6.36 are supported.
	110
	111
	112	Notes
	113	-----
	114
	115	### About perf PMU counters support
	116
	117	Each PMU counter has its zero value set when it is attached to a context with
	118	add-context. Therefore, it is normal that the same counters attached to both the
	119	stream context and event context show different values for a given event; what
	120	matters is that they increment at the same rate.