Community

Where is the LTTng community?

Mailing list

For help and developer discussions, see the LTTng mailing list.

You can send mails to the list without being registered, but non-member posts are moderated.

Internet Relay Chat

We're available on IRC, on the OFTC network, in the #lttng channel.

Use: irc://irc.oftc.net/lttng.

Bug reporting

You can report bugs regarding any LTTng component by creating a new issue in the project's bug tracker.

Continuous integration

Jenkins is used to test builds as code changes occur and ensure code quality. The current project statuses are available on the online interface.

LTTng Review

LTTng Review is a Gerrit instance used to submit, discuss, and track proposed patches.

Getting involved

Helping LTTng's community

LTTng is an open source project welcoming contributions by volunteers from around the world.

Most people believe that contributing to an open source project involves writing code, but there are actually multiple other ways to help out. Here are a few ways your help would be greatly appreciated by the LTTng community:

Mailing list + IRC

One of the easiest ways to get involved is to participate in the various discussions of the mailing list or on IRC and help people use LTTng.

Testing + bug reporting

Testing new releases and reporting bugs on the bug tracker is also a great way to contribute. Refer to the Bug reporting guidelines below before reporting a bug.

Documentation

Improving the project's documentation is always welcome. Refer to its contributor's guide before creating pull requests.

Code improvements

You can also submit code improvements and bug fixes if you are a developer. Refer to the Contributor's guide below for code contributions.

Getting involved

Helping LTTng's community

Bug reporting guidelines

Help us help you!

Reporting bugs is an excellent way to contribute to the LTTng project. Should you be interested in reporting a bug, please make sure that it's complete by reading the following guidelines carefully.

The most important thing for developers is to understand how to reproduce the bug. If a developer can successfully reproduce a bug and knows what is the expected software behavior, he's given all the necessary tools to fix the issue.

You must post bug reports on the LTTng bug tracker.

Mandatory stuff

You must provide the following items for the bug to be reproducible:

  • Component(s) involved: LTTng-tools, LTTng-UST, LTTng-modules, liburcu, or Babeltrace? If the bug involves more than one component, report it under the Redmine LTTng umbrella project.
  • Component version: Full version of the software exhibiting the bug (--version option) or Git commit hash for custom builds.
  • System information:
    • Architecture, number of CPUs.
    • Operating system version (uname -a) and distribution.

Expected vs. actual results

Make sure you provide a short description which explains the nature of the bug: what is the expected behavior and what are you actually observing?

Avoid using negations in your description. Explain what should happen, not what shouldn't happen. Explain what is happening, not what's not happening.

Bad examples:

The event should not be disabled after tracing is stopped.

The command is not returning 0 after a successful execution.

Good examples:

The consumer daemon's execution should terminate after this operation.

Only 4 out of 5 events are recorded.

We need context!

When you describe the actual results, add as much context as possible. Useful context includes:

Logs

Copy the relevant logs to the bug's description.

  • LTTng-UST: Set the LTTNG_UST_DEBUG environment variable to 1 before running your application.
  • LTTng-tools: Start the session daemon manually with the -vvv and --verbose-consumer arguments.

Debugging information

If the bug involves a segmentation fault in LTTng-tools, you should compile the project manually with the -g GCC option and without optimizations (-O0). You can run the configure script as such:

CFLAGS="-g -O0" ./configure

Then, the following items are required:

  • A core file.
  • The full backtraces of the session daemon and the consumer daemon as returned by GDB (command thread apply all bt full).

Running processes

It's often useful to have the list of LTTng-related processes running on the system:

ps -wwaux | grep '[l]ttng'

Loaded kernel modules

If the bug involves LTTng-modules (Linux kernel tracing), include the list of loaded LTTng-related kernel modules:

lsmod | grep lttng

Steps to reproduce the bug

This is the most important section. Its goal is to show the developers how to reproduce the bug, step by step.

You may write prerequisites to reduce the number of steps here, for example:

Prerequisite: a tracing session exists with two kernel domain channels named kern1 and kern2.

In this last example, the steps to create a tracing session and enable two kernel domain channels are summarized by a simple prerequisite.

Once you've laid out the steps to reproduce the bug, a good practice is to follow them and see if the bug is actually reproduced. This help ensure you didn't forget an important step.

Contributor's guide

Useful guidelines for contributing

The LTTng project is open source and welcomes contributions from anyone. This guide will walk you through the process of contributing a patch to LTTng.

Get the source code

We use Git to control the versions of the LTTng project. How to use Git is beyond the scope of this guide, but its official website provides many great tutorials. Please refer to the Download section for the official LTTng Git repositories.

Programming style

We use the Linux kernel coding style with one addition for LTTng-tools only: single-line if/for/while control statements must be wrapped in braces.

/* not good */
if (this == that)
    goto fail;

/* good */
if (this == that) {
    goto fail;
}

Although the LTTng code base is primarily written in C, it does contain shell, Perl, Python, and Java code. There is no official coding standard for these languages. However, we encourage you to use a style consistent with the rest of the code written in that language.

Create a patch

To prepare your changes for submission, commit them to your local branch while following the guidelines below.

The commit's subject (first line) should:

  • Begin with an uppercase letter.
  • Be written in the present tense.
  • Not exceed 72 characters in length.
  • Not end with a period.
  • Be prefixed with Fix: if the commit fixes a bug.

The commit message's body should be as detailed as possible and explain the reasons behind the proposed change. You must mention any related bug report at the end of the message with the #123 format, where 123 is the bug number:

  • Use Refs: #123 if the patch is related to bug 123, but does not fix it yet.
  • Use Fixes: #123 to indicate that this patch fixes the bug.

Make sure to sign-off your submitted patches (the -s argument to Git's commit and format-patch commands).

A patch must be as focused as possible. Do not, for instance, fix a bug and correct the indentation of an unrelated block of code as part of the same patch.

Here's a complete example:

Fix: use this instead of that in some context

Ball tip jowl beef ribs shankle, leberkas venison turducken tail pork
chop t-bone meatball tri-tip. Tongue beef ribs corned beef ball tip
kevin ground round sausage rump meatloaf pig meatball prosciutto
landjaeger strip steak. Pork pork belly beef.

Biltong turkey porchetta filet mignon corned beef. T-bone bresaola
shoulder meatloaf tongue kielbasa.

Fixes: #321
Refs: #456
Refs: #4972

Signed-off-by: Janine Sutto <jsutto@janine.su>

Submit a patch

LTTng's development flow is primarily based on Gerrit Code Review, although we also accept email-based patch series on the lttng-dev mailing list, and pull requests on our GitHub mirrors.

The lttng-dev mailing list is also used to share and comment on RFCs and answer questions.

To LTTng Review using git-review (preferred)

  1. Sign-in to LTTng Review (Gerrit instance) using your GitHub account and add an SSH public key.

  2. Install the git-review plugin. The plugin is available through the package manager of several Linux distributions including: Ubuntu, Debian, Fedora, openSUSE, and Alpine.

  3. In the checked-out repository, initialize the git-review state by running git review -s.

  4. Submit the changes by running git review.

    Consult the git-review documentation for more details about how the commands work, and the Gerrit user documentation to learn more about Gerrit.

  5. When your submission is ready for review, you may add the user project-maint as a reviewer.

    project is the name of the project you are submitting a change to.

    For example:

    • lttng-tools-maint
    • lttng-modules-maint
    • lttng-ust-maint

To lttng-dev using email

  1. Create one or more patch files corresponding to your Git commits.

    You can use Git's format‑patch command to generate a patch file.

    For example, the following command line generates a patch from the latest commit:

    $
    git format-patch -N1 -s --subject-prefix="PATCH project"

    Replace project with one of:

    • lttng-tools
    • lttng-ust
    • lttng-modules
    • babeltrace (the Babeltrace project uses the LTTng mailing list)
  2. If your patch is for the LTTng-tools project, run the checkpatch.pl script on your patch file and correct any reported errors:

    $
    extras/checkpatch.pl --no-tree 0001-Fix...patch
  3. Send your patch to the LTTng development mailing list.

    You can use Git's send‑email command to do so:

    $
    git send-email --suppress-cc=self --to=lttng-dev@lists.lttng.org *.patch

    Make sure you are subscribed to the mailing list to follow and take part in discussions about your changes.

    You can also join the file to an email as an attachment if you can't send the patch directly using git send‑email.

To GitHub

  1. If you do not have one, create a GitHub account.

  2. Fork the project repository.

  3. Push your locally submitted changes to a new branch in your fork of the project repository.

  4. Open a pull request.

Reviews

Once you have posted your patch to LTTng Review, the mailing list, or to another accepted platform, other contributors may propose modifications to your patch. This is completely normal. This collaborative code review is an integral part of the open source development process in general, and LTTng makes no exception.

Keep in mind that reviewing patches is a time-consuming process. Reviewers may not post comments right away. The current release cycle phase and the complexity of the proposed changes can affect the delays. If you think that we might have forgotten your patch, please mention it on the #lttng IRC channel rather than resubmitting.

Release cycle

The LTTng project follows a release cycle that alternates between development and release candidate (RC) phases. The master branch is feature-frozen during RC phases; only bug fixes are accepted during this period. However, mailing list subscribers may still review patches which add new functionality during an RC phase. We post the upcoming features and release dates in a monthly digest on the mailing list.

Contributor's guide

Useful guidelines for contributing