Quickstart

The easiest way to use vlttng is to use the vlttng-quick command. This
command interactively asks you a few questions to create a basic
vlttng command line that you can use later or immediately after.

How does it work?

The vlttng command does the following:

It reads one or more profiles that you give on the command line to
know which packages to fetch and build.

It fetches and extracts the requested packages. Git, with a specific
branch/tag/commit, as well as HTTP/FTP tarball sources are supported.
The Git clone URL can point to a local Git repository using the
file:// protocol.

It builds one package at a time, setting some environment variables
and configure options so that the dependencies of the packages are
contained within the virtual environment.

It creates an activate script which you can source from your
Bash/Zsh prompt to “enter” the virtual environment. This script sets
a few environment variables, like PATH, LD_LIBRARY_PATH, and
PYTHONPATH, to achieve this. By default, it also prepends the name
of the virtual environment directory to your shell prompt for you to
know which virtual environment is active.

When you source the activate script, if the LTTng-modules project is
part of the effective profile, vlttng removes the currently loaded
LTTng kernel modules and sets the MODPROBE_OPTIONS environment
variable so that the LTTng session daemon loads the virtual environment
modules.

The root build-env property defines the base build environment
variables. They are set when building the projects. vlttng also
passes exported shell variables to the executed programs, so you can
do:

CC=clang CFLAGS='-O0 -g3' vlttng ...

The root virt-env property defines the virtual environment variables,
which are set when activating the virtual environment. Exported
shell variables, when invoking vlttng, are not set when activating
the resulting virtual environment.

The available project names, as of this version, are:

babeltrace

elfutils

glib

libxml2

lttng-analyses

lttng-modules

lttng-tools

lttng-ust

popt

tracecompass

lttng-scope

urcu

The build-env property of a specific project defines environment
variables to be used only during the build stage of this project. A
project-specific build-time environment variable overrides a base
build-time environment variable sharing its name.

When the source property contains a Git URL, or when checkout
property is set, the checkout property indicates which branch, tag,
or commit to check out. When it’s not specified, vlttng checks out
the master branch.

The configure property specifies the options to pass to the
configure script of a given project. vlttng handles some options
itself, like --prefix and --without-lttng-ust, to create a working
virtual environment.

The profile above can be saved to a file, for example my-profile.yml,
and you can create a virtual environment out of it:

vlttng -p my-profile.yml virt

When you give multiple profiles to vlttng, the first profile is
“patched” with the second, which is then patched with the third, and
so on. Nonexistent properties are created; existing ones are replaced
recursively. The configure properties are joined. For example, let’s
add the following profile (call it more.yaml) to the example above:

Make the output verbose

By default, vlttng hides the standard output and error of the commands
it runs. In this mode, vlttng prints all the commands to run and the
exported environment variables along with comments, so that you can
“replay” the entire output as is to create the same virtual
environment (except for the activate script which would not be
generated).

You can use the --verbose (-v) option to also print the standard
output and error of all the executed commands, and the effective profile
used to create the virtual environment.

Define the number of make jobs

vlttng passes its --jobs (-j) option as is to make.

activate script options

When you source the activate script, you can use the following
environment variables to alter its behaviour:

VLTTNG_NO_RMMOD

Set to 1 to disable the unloading of the currently loaded LTTng
kernel modules.

VLTTNG_NO_PROMPT

Set to 1 to keep your current shell prompt after the activation.

Use sudo

If you use sudo when the virtual environment is activated, make sure
to use its --preserve-env (-E) option, so that the virtual
environment is preserved when it executes the command.

For example, to start a root session daemon which loads the LTTng kernel
modules installed in the virtual environment:

sudo --preserve-env lttng-sessiond --daemonize

Trace a Java application

When the LTTng-UST project is built with a Java agent, the activation
of the virtual environment sets the VLTTNG_CLASSPATH environment
variable to a Java class path to use when you compile and run
Java applications.

Trace a Python application

If the LTTng-UST Python agent is built and installed in the virtual
environment, there’s nothing special to do to trace a Python
application: the PYTHONPATH environment variable contains the path to
the LTTng-UST Python agent package in the virtual environment. You can
import the lttngust package as usual.

Update a project with a Git source

vlttng generates the following scripts in the virtual environment’s
root directory (name is the project name):

conf-name.bash

Runs the configuration step of the project.

build-name.bash

Runs the build step of the project.

install-name.bash

Runs the install step of the project.

update-name.bash (only with a Git source)

Fetches the project’s configured Git remote, checks out the latest
version of the configured branch, and runs conf-name.bash,
build-name.bash, and install-name.bash.

Important

Use those scripts with caution. For a stable branch, they
should work most of the time. For the master branch, some required
implicit configuration and build command lines might be missing from the
scripts when you use the update script.