Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/eepp/vlttng

Create LTTng virtual environments
https://github.com/eepp/vlttng

lttng sandbox virtualenv

Last synced: about 2 months ago
JSON representation

Create LTTng virtual environments

Awesome Lists containing this project

README 

        
// Render with Asciidoctor



= vlttng

Philippe Proulx 

:toc:



image:https://img.shields.io/pypi/v/vlttng.svg?label=Latest%20version[link="https://pypi.python.org/pypi/vlttng"]



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



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



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



----

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



[source,yaml]

----

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:



[source,yaml]

----

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:



[source,yaml]

----

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

== 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:: {empty}

+

----

PATH=REPLACEMENT

----



Append to a property:: {empty}

+

----

PATH+=APPEND

----



Remove a property:: {empty}

+

----

!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

<>:



----

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



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

----



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