Bonjour!

Welcome to the LTTng control library C API (liblttng-ctl) documentation!

The Linux Trace Toolkit: next generation is an open-source software package used for correlated tracing of the Linux kernel, user applications, and user libraries.

liblttng-ctl, which is part of the LTTng-tools project, makes it possible to control LTTng tracing, but also to receive notifications when specific events occur.

Plumbing

The following diagram shows the components of LTTng:

Components of LTTng.

As you can see, liblttng-ctl is a bridge between a user application and a session daemon (see lttng-sessiond(8) and Session daemon connection).

The lttng(1) command-line tool which ships with LTTng-tools, for example, uses liblttng-ctl to perform its commands.

See the Components of LTTng section of the LTTng Documentation to learn more.

Contents

This API documentation has three main modules:

• The recording session API makes it possible to create, manipulate (take a snapshot, rotate, clear, and the rest), and destroy recording sessions.

  A recording session is a per-Unix user dialogue for everything related to event recording.

  A recording session owns channels which own recording event rules. Those objects constitute the main configuration of a recording session.

• The instrumentation point listing API makes it possible to get details about the available LTTng tracepoints, Java/Python loggers, and Linux kernel system calls without needing any recording session.

• The trigger API makes it possible to create and register triggers.

  A trigger associates a condition to an action: when the condition of a trigger is satisfied, LTTng attempts to execute its action.

  This API is fully decoupled from the recording session API.

  Amongst the interesting available trigger conditions and actions are the “event rule matches” condition and the “notify” action. With those, your application can receive an asynchronous message (a notification) when a specified event rule matches an LTTng event.

The three modules above often refer to the General API which offers common enumerations, macros, and functions.

See Topics for the complete table of contents.

Build with liblttng-ctl

To build an application with liblttng-ctl:

Header file

Include lttng/lttng.h:

#include <lttng/lttng.h>

With pkg-config, get the required C flags with:

$ pkg-config --cflags lttng-ctl

Linking

Link your application with liblttng-ctl:

$ cc my-app.o ... -llttng-ctl

With pkg-config, get the required linker options with:

$ pkg-config --libs lttng-ctl