// Render with Asciidoctor
= vlttng Philippe Proulx https://eepp.ca/ :toc:
vlttng is a tool which creates a virtual environment (a sandbox) to run specific versions of the http://lttng.org/[LTTng] packages.
The https://babeltrace.org/[Babeltrace]{nbsp}1 and{nbsp}2, https://liburcu.org/[Userspace RCU], https://github.com/lttng/lttng-analyses[LTTng analyses], https://github.com/lttng/lttng-scope[LTTng Scope], and http://tracecompass.org/[Trace Compass] projects are also supported, as well as some of the project dependencies.
== Install vlttng
To install vlttng on the system:
pip3:--
To install vlttng in your home directory:
pip3:--
The commands are installed in ~/.local/bin.
Two new commands are available: vlttng and vlttng-quick.
== Quickstart
The easiest way to get started with vlttng is to use its 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.
== How does vlttng work?
The vlttng command does the following:
. Reads one or more profiles that you give on the command line to know which packages to fetch and build.
. Fetches and extracts the requested packages.
+
vlttng supports Git with a specific branch/tag/commit as well as
HTTP/FTP tarball sources. The Git clone URL can point to a local Git
repository using the file:// protocol.
. 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.
. 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.
Example:
Here, we're using five profiles to create a virtual environment in the
virt directory. Source the generated activate script to enter the
virtual environment:
Your prompt starts with [virt] after this (the name of the virtual
environment directory).
"Exit" the virtual environment with the vlttng-deactivate command.
Your prompt will return to its previous value.
== Write and use profiles
A vlttng profile is a layer of configuration. You can use multiple profiles to create an effective profile.
The project ships with more than 1000 default profiles. Use
vlttng --list-default-profiles to list their names.
Profiles are written in YAML. Here's an example:
A few things to note here:
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:
The root virt-env property defines the virtual environment
variables, which are set when you activate the virtual environment.
Exported shell variables when you run vlttng are not set when
you activate the resulting virtual environment.
The available project names, as of this version, are:
babeltrace2
babeltrace
elfutils
glib
libxml2
lttng-analyses
lttng-modules
lttng-scope
lttng-tools
lttng-ust
popt
tracecompass
** 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 the 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 takes care of some
options itself, like --prefix and --without-lttng-ust, to create a
working virtual environment.
You can save the profile above to a file, for example my-profile.yml,
and then you can create a virtual environment out of it:
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, as such:
configure properties are joined.For example, let's add the following profile (call it more.yaml) to
the example above:
With this command:
the effective profile is:
[[override]] == Override a profile property
Replace, append to, and remove effective profile properties (after
vlttng has merged all the profiles given with the --profile option
as an effective profile) with the --override (-o) option.
The three override operations are:
PATH is the path to the property, from the root of the profile, using
a dot-separated list of keys to find recursively.
Example:
In replace and append modes, vlttng creates the property if it does
not exist. This allows you to create projects on the command line:
vlttng applies the overrides in command line order.
== Ignore a project
Ignore specific projects that exist in the effective profile with the
--ignore-project (-i) option:
This is the equivalent of removing the project's property with an <<override,override>>:
== 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.
The default value of the --jobs option is the number of active CPUs on
your system.
== activate script options
When you source the activate script, 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 LTTng session daemon which loads the LTTng kernel modules installed in the virtual environment:
== 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.
Example:
== Use the virtual environment's Python packages
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.
As such, you can import the babeltrace and bt2 Python{nbsp}3
packages directly.
== 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.