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

Stack Overflow

Ask your LTTng-related question on Stack Overflow by tagging it with 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.

Twitter

Follow us on Twitter: @lttng_project. Tweet with the #lttng hashtag.

Getting involved

Helping LTTng's community

LTTng is an open source project built by a team of 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

Being an open source project, the LTTng project 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.

Coding standard

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 and send a patch

LTTng's development flow is primarily email-based, although we also accept pull requests on our GitHub mirrors. If you create a GitHub pull request, please make sure you still follow the guidelines below.

Like a lot of open source projects, patches are submitted and reviewed on the project's development mailing list, lttng-dev (lttng-dev@lists.lttng.org). Users and contributors also use the mailing list to share and comment on RFCs and answer questions.

To contribute a patch to the LTTng project:

  1. Commit your changes to your local branch.

    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 signify 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>
    
  2. 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)
  3. 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
  4. 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.

Reviews

Once you have posted your patch to the mailing list, or submitted your changes as a GitHub pull request, 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