- Install vlttng
- Quickstart
- How does vlttng work?
- Write and use profiles
- Override a profile property
- Ignore a project
- Make the output verbose
- Define the number of make jobs
activate
script options- Use
sudo
- Trace a Java application
- Use the virtual environment’s Python packages
- Update a project with a Git source
vlttng is a tool which creates a virtual environment (a sandbox) to run specific versions of the LTTng packages.
The Babeltrace 1 and 2, Userspace RCU, LTTng analyses, LTTng Scope, and Trace Compass projects are also supported, as well as some of the project dependencies.
To install vlttng on the system:
-
Use
pip3
:$ sudo pip3 install --upgrade vlttng
To install vlttng in your home directory:
-
Use
pip3
:$ pip3 install --user --upgrade vlttng
The commands are installed in
~/.local/bin
.
Two new commands are available: vlttng
and vlttng-quick
.
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.
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
, andPYTHONPATH
, 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 theMODPROBE_OPTIONS
environment variable so that the LTTng session daemon loads the virtual environment modules.
Example:
$ vlttng -p lttng-stable-2.11 -p babeltrace2-master -p babeltrace2-python \ -p lttng-tools-no-lttng-relayd -p urcu-stable-0.10 virt
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:
$ . ./virt/activate
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.
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:
build-env:
CFLAGS: -O0 -g3
virt-env:
ENABLE_FEATURE: '1'
SOME_PATH: /path/to/omg
projects:
lttng-tools:
source: 'git://git.lttng.org/lttng-tools.git'
checkout: stable-2.11
build-env:
CC: clang
CFLAGS: ''
lttng-ust:
source: 'http://lttng.org/files/lttng-ust/lttng-ust-2.11.0.tar.bz2'
configure: --enable-python-agent
lttng-modules:
source: 'git://git.lttng.org/lttng-modules.git'
checkout: stable-2.11
urcu:
source: 'git://git.liburcu.org/userspace-rcu.git'
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:$ CC=clang CFLAGS='-O0 -g3' vlttng ...
-
The root
virt-env
property defines the virtual environment variables, which are set when you activate the virtual environment. Exported shell variables when you runvlttng
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 thecheckout
property is set, thecheckout
property indicates which branch, tag, or commit to check out. When it’s not specified,vlttng
checks out themaster
branch. -
The
configure
property specifies the options to pass to theconfigure
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:
$ 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, as such:
-
Nonexistent properties are created.
-
Existing properties are replaced recursively.
-
The
configure
properties are joined.
For example, let’s add the following profile (call it more.yaml
) to
the example above:
build-env:
CFLAGS: -O0
SOMEVAR: ok
projects:
lttng-tools:
source: 'https://github.com/lttng/lttng-tools.git'
lttng-ust:
configure: --enable-java-agent-jul
With this command:
$ vlttng -p my-profile.yml -p more.yaml virt
the effective profile is:
build-env:
CFLAGS: -O0
SOMEVAR: ok
projects:
lttng-tools:
source: 'https://github.com/lttng/lttng-tools.git'
checkout: stable-2.11
build-env:
CC: clang
CFLAGS: ''
lttng-ust:
source: 'http://lttng.org/files/lttng-ust/lttng-ust-2.11.0.tar.bz2'
configure: --enable-python-agent --enable-java-agent-jul
lttng-modules:
source: 'git://git.lttng.org/lttng-modules.git'
checkout: stable-2.11
urcu:
source: 'git://git.liburcu.org/userspace-rcu.git'
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:
- Replace a property
-
PATH=REPLACEMENT
- Append to a property
-
PATH+=APPEND
- Remove a property
-
!PATH
PATH
is the path to the property, from the root of the profile, using
a dot-separated list of keys to find recursively.
Example:
-o projects.lttng-tools.configure+=--disable-bin-lttng-relayd \ -o '!projects.lttng-ust.checkout' \ -o build-env.CC=clang
In replace and append modes, vlttng
creates the property if it does
not exist. This allows you to create projects on the command line:
-o projects.lttng-tools.source=https://github.com/lttng/lttng-tools.git \ -o projects.lttng-tools.checkout=v2.11.0 \ -o projects.lttng-tools.configure='--disable-bin-lttng --disable-man-pages'
vlttng
applies the overrides in command line order.
Ignore specific projects that exist in the effective profile with the
--ignore-project
(-i
) option:
$ vlttng -p lttng-stable-2.11 -p urcu-master -i lttng-ust virt
This is the equivalent of removing the project’s property with an override:
$ vlttng -p lttng-stable-2.11 -p urcu-master -o '!projects.lttng-ust' virt
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.
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.
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.
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:
$ sudo --preserve-env lttng-sessiond --daemonize
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:
$ javac -cp $VLTTNG_CLASSPATH MyClass.java $ java -cp $VLTTNG_CLASSPATH:. MyClass
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 3
packages directly.
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
, andinstall-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.
|