This repository contains helper scripts to record traces with LTTng for many common use cases.
This scripts requires the following packages to run:
- LTTng
- Python >= 3.4
- PyYaml often available in distros as
python3-yaml
orpython-yaml
- Setuptools (for installation, not needed if running from directory)
To install the helper script and profiles from the source
- Install the required dependencies.
- run the setup script from the project's root directory
$ git clone https://github.com/tahini/lttng-utils.git
$ cd lttng-utils
$ sudo python3 setup.py install
To install LTTng utils directly from the git repository
- Install the required dependencies.
- Make sure
pip
for Python 3 is installed on your system. The package is namedpython3-pip
on most distributions (python-pip
on Arch Linux). - Use
pip3
to install LTTng analyses:
$ sudo pip3 install --upgrade git+https://github.com/tahini/lttng-utils.git@master
To simply record a trace with common kernel events that can then be analyzed with most of the analyses in lttng-analyses or opened in Trace Compass, use the following command: Tracing can be stopped by pressing ctrl-c.
$ lttng-record-trace
To trace only during a specific application's lifetime, just add the application to trace to the arguments of the commands, for example, to trace only the ls -alt
command
$ lttng-record-trace ls -alt
More options are available for tracing. See the helper
$ lttng-record-trace --help
LTTng-utils comes with a set of pre-defined profiles for common tracing use cases. Users can define their own profiles as well. The lttng-record-trace --list-profiles
command will show the paths that are searched for profile, typically, the builtin script's path, $HOME/.lttng-utils/profiles/
and a profiles/
directory in the current directory.
Here is the output of the lttng-record-trace --list-profiles
command for the builtin profiles:
Available profiles:
timer The kernel timer events
network The kernel network events
sched The scheduler events of the kernel
mm The page allocation events of the kernel (they are very numerous)
kernel A subset of kernel events sufficient and necessary to make most Trace Compass analyses
Includes profiles: sched, interrupt, network, timer, statedump_k, disk
cyg_profile Enable function entry and exit tracepoints for a -finstrument-functions compiled application
statedump_k The lttng kernel statedump events
interrupt The kernel events for interrupts and software interrupts
disk The kernel events for disk analysis
libc Enable the lttng UST libc wrapper
cyg_profile_fast Enable fast function entry and exit tracepoints for a -finstrument-functions compiled application
For example, to test an application instrumented with the -finstrument-functions
compiler flag, you can run lttng-record-trace -p cyg_profile ./myapp
or lttng-record-trace -p cyg-profile,kernel ./myapp
to trace the system along with the application.
To add your own profile, you can create a new file named myprofile.profile
in one of those directory mentioned above and edit it. Profiles are yaml files with the following structure:
desc:
A description of the profile that will appear when listing profiles
includes:
list of profiles to include in this one
kernel:
list of kernel events to enable, 'syscall' being a special event to enable all syscalls
ust:
list of userspace events to enable
jul:
list of JUL events to enable
preload:
list of libraries to preload when running the application to trace
Then you can run the trace recording script with the profile like this:
$ lttng-record-trace -p myprofile