vlttng

Table of Contents

• 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.

Install vlttng

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.

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:

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

2. 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.

3. 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.

4. 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:

$ 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.

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:

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 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:

$ 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'

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:

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 a project

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

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.

Also use the env command, setting the PATH variable to its current value because otherwise sudo won’t find 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 env PATH="$PATH" 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.

Example:

$ javac -cp $VLTTNG_CLASSPATH MyClass.java
$ java -cp $VLTTNG_CLASSPATH:. MyClass

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 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.