Create virtual LTTng environments with vlttng

Philippe Proulx on 31 October 2016

In my day to day job at EfficiOS, I often have to manually test different versions and configurations of LTTng. The typical way to test LTTng 2.7 if LTTng 2.8 is installed, for example, is, for each of the three LTTng projects (LTTng-tools, LTTng-UST, and LTTng-modules):

Uninstall the current version (2.8).
Check out version 2.7.
Configure, build, and install version 2.7.

This whole manual process becomes painful over time. I'm not even mentioning the situations where I also need to test different versions of the tools' dependencies, like Glib and Libxml2. The same laborious process applies to Babeltrace.

In an ideal world, I would have multiple environments containing different versions and configurations of the tools and dependencies which form the LTTng ecosystem. This is totally possible with the various environment variables and configure flags (--prefix, --with-lttng-ust-prefix, and the rest) of the projects. And this is exactly what vlttng exploits to achieve this. vlttng is a project I've been working on in my spare time.

In this article I explain what vlttng is exactly, after which I show a concrete example.

vlttng: overview

I'm a big fan of virtualenv. This tool is used to create isolated Python environments. A Python virtual environment has its own packages, its own version of Python, and its own version of pip. It's as easy as this to create one:

virtualenv my-env

Then you get a directory named my-env which contains the virtual environment tree, as well as an activation script. You can "enter" the virtual environment by sourcing this script:

. ./my-env/bin/activate

Your prompt is prefixed with (my-env) to indicate that you're in this virtual environment. Now, everything you do that's Python-related only has an effect on this directory. For example, let's install a few packages using pip and start ipython:

pip install zmq
pip install pyyaml
pip install flask
ipython

pip installs the packages in my-env and ipython uses the Python interpreter found in my-env.

This is an awesome tool if you are a Python developer because you can create a Python environment with a very specific set of packages (with precise versions).

Inspired by virtual-env, I made vlttng to create LTTng virtual environments. The concept is very similar.

The vlttng command-line tool knows how to download, configure, build, and install each LTTng-related project, including Babeltrace, LTTng analyses, and Trace Compass, as well as all their dependencies. The tool knows how to configure the projects depending on which other projects need to be built and installed.

I also created a command-line tool named vlttng-quick which interactively asks you a few questions to generates a vlttng command line. vlttng-quick can also run this command line once you answer its questions.

Some notable features of the generated virtual environment are:

vlttng downloads and installs Apache log4j in the virtual environment when it detects that the LTTng-UST Java agent for log4j needs to be installed.
activate sets the VLTTNG_CLASSPATH environment variable when it detects that the LTTng-UST Java agent needs to be installed. You can use this environment variable when you build and run your Java application:
```
javac -cp $VLTTNG_CLASSPATH MyApp.java
java -cp $VLTTNG_CLASSPATH:. MyApp
```
activate updates the PYTHONPATH environment variable so that the Babeltrace Python bindings, LTTng analyses, and LTTng-UST Python agent packages are found in the virtual environment first.
activate updates the PKG_CONFIG_PATH environment variable so that pkg-config finds the metadata in the virtual environment first:
```
pkg-config --libs lttng-ust
```
activate updates the MANPATH environment variable so that you can read the environment's man pages using man as usual:
```
man lttng-enable-event
man babeltrace
```
activate updates the CPPFLAGS and LDFLAGS environment variables so that you can build an application which uses any build system that recognizes those variables against the headers and libraries of the virtual environment:
```
./configure && make
```
vlttng generates scripts in the virtual environment directory to reconfigure, rebuild, reinstall, and update projects that were installed from a Git source:
```
$VLTTNG/update-lttng-tools.bash
```

vlttng can probably help you if:

You want to contribute to one of the LTTng or Babeltrace projects.
You want to test a specific configuration of the tools without tainting the system.
You want to use LTTng on a distribution with no LTTng packages.
You want to cross-compile the tools.

Let's try it!

Install vlttng:

sudo pip3 install --upgrade vlttng

If you're not fond of a system-wide installation, install it for you only:

pip3 install --user --upgrade vlttng

In this case, make sure $HOME/.local/bin is part of your PATH.

Let's create an LTTng virtual environment with LTTng 2.8, Babeltrace 1.4, the latest Libxml2, and the latest LTTng analyses:

vlttng -p lttng-stable-2.8 -p babeltrace-stable-1.4 -p libxml2-master \
       -p lttng-analyses-master --jobs=4 my-env

The output of the command shows the current operation. Once the command exits, you can activate the generated virtual environment:

. ./my-env/activate

Since the LTTng-modules project is part of the profile, the activation script removes the currently loaded LTTng kernel modules, if any.

Your prompt is prefixed with [my-env] to indicate that you're in this virtual LTTng environment.

Now, you can use the tracers as usual:

sudo --preserve-env lttng-sessiond --daemonize
lttng create
lttng enable-event --kernel sched_'*'
lttng start
# ...
lttng stop
lttng view
lttng destroy

You need to use the --preserve-env option of sudo to preserve the virtual environment variables when sudo runs the session daemon.

By default, LTTng creates the trace in the my-env/home/lttng-traces directory.

The lttng view command executes the babeltrace program installed in my-env.

Once you're done, exit this virtual environment:

vlttng-deactivate

Make sure to read the project's README to learn how to customize profiles, override profile properties, ignore projects, and more.

← Back to LTTng's blog