Docs/2.12

Linux Trace Toolkit: next generation

$
#
echo Command line as a regular user
echo Command line as a the `root` user
$
lttng track --userspace --vuid=http,999 --vgid=mysql,9
lttng_statedump_cpu_topology:
  architecture: x86
  cpu_id: 0
  vendor: GenuineIntel
  family: 6
  model: 142
  model_name: Intel(R) Core(TM) i7-7600U CPU @ 2.80GHz
  physical_id: 0
  core_id: 0
  cores: 2

#
#
apt-add-repository ppa:lttng/stable-2.12
apt-get update
#
#
#
apt-get install lttng-tools
apt-get install lttng-modules-dkms
apt-get install liblttng-ust-dev
#
apt-get install liblttng-ust-agent-java
#
apt-get install python3-lttngust
#
#
#
apt-get install lttng-modules-dkms
apt-get install liblttng-ust-dev
apt-get install lttng-tools
#
apt-get install liblttng-ust-agent-java
#
apt-get install python3-lttngust
#
#
apk add lttng-tools
apk add lttng-ust-dev
$

cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-modules/lttng-modules-latest-2.12.tar.bz2 &&
tar -xf lttng-modules-latest-2.12.tar.bz2 &&
cd lttng-modules-2.12.* &&
make &&
sudo make modules_install &&
sudo depmod -a
$
make menuconfig
IMAGE_INSTALL_append = " lttng-tools lttng-modules lttng-ust"
$

cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-modules/lttng-modules-latest-2.12.tar.bz2 &&
tar -xf lttng-modules-latest-2.12.tar.bz2 &&
cd lttng-modules-2.12.* &&
make &&
sudo make modules_install &&
sudo depmod -a
$

cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-ust/lttng-ust-latest-2.12.tar.bz2 &&
tar -xf lttng-ust-latest-2.12.tar.bz2 &&
cd lttng-ust-2.12.* &&
./configure &&
make &&
sudo make install &&
sudo ldconfig
$

cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-tools/lttng-tools-latest-2.12.tar.bz2 &&
tar -xf lttng-tools-latest-2.12.tar.bz2 &&
cd lttng-tools-2.12.* &&
./configure &&
make &&
sudo make install &&
sudo ldconfig
#

lttng-sessiond
Warning: No tracing group detected
modprobe: ERROR: could not insert 'lttng_ring_buffer_client_discard': Key was rejected by service
Error: Unable to load required module lttng-ring-buffer-client-discard
Warning: No kernel tracer available
#
lttng create my-kernel-session --output=/tmp/my-kernel-trace
#
#
lttng list --kernel
lttng list --kernel --syscall
#
#
lttng enable-event --kernel sched_switch,sched_process_fork
lttng enable-event --kernel --syscall open,close
#
lttng enable-event --kernel --all
#
lttng start
#
lttng destroy
#
chown -R $(whoami) /tmp/my-kernel-trace
#undef TRACEPOINT_PROVIDER
#define TRACEPOINT_PROVIDER hello_world

#undef TRACEPOINT_INCLUDE
#define TRACEPOINT_INCLUDE "./hello-tp.h"

#if !defined(_HELLO_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
#define _HELLO_TP_H

#include <lttng/tracepoint.h>

TRACEPOINT_EVENT(
    hello_world,
    my_first_tracepoint,
    TP_ARGS(
        int, my_integer_arg,
        char*, my_string_arg
    ),
    TP_FIELDS(
        ctf_string(my_string_field, my_string_arg)
        ctf_integer(int, my_integer_field, my_integer_arg)
    )
)

#endif /* _HELLO_TP_H */

#include <lttng/tracepoint-event.h>

#define TRACEPOINT_CREATE_PROBES
#define TRACEPOINT_DEFINE

#include "hello-tp.h"

$
gcc -c -I. hello-tp.c
#include <stdio.h>
#include "hello-tp.h"

int main(int argc, char *argv[])
{
    int x;

    puts("Hello, World!\nPress Enter to continue...");

    /*
     * The following getchar() call is only placed here for the purpose
     * of this demonstration, to pause the application in order for
     * you to have time to list its tracepoints. It's not needed
     * otherwise.
     */
    getchar();

    /*
     * A tracepoint() call.
     *
     * Arguments, as defined in hello-tp.h:
     *
     * 1. Tracepoint provider name   (required)
     * 2. Tracepoint name            (required)
     * 3. my_integer_arg             (first user-defined argument)
     * 4. my_string_arg              (second user-defined argument)
     *
     * Notice the tracepoint provider and tracepoint names are
     * NOT strings: they are in fact parts of variables that the
     * macros in hello-tp.h create.
     */
    tracepoint(hello_world, my_first_tracepoint, 23, "hi there!");

    for (x = 0; x < argc; ++x) {
        tracepoint(hello_world, my_first_tracepoint, x, argv[x]);
    }

    puts("Quitting now!");
    tracepoint(hello_world, my_first_tracepoint, x * x, "x^2");

    return 0;
}

$
gcc -c hello.c
$
gcc -o hello hello.o hello-tp.o -llttng-ust -ldl
$
./hello world and beyond
Hello, World!
Press Enter to continue...
$
lttng-sessiond --daemonize
$
lttng list --userspace
$
lttng create my-user-space-session
$
lttng enable-event --userspace hello_world:my_first_tracepoint
$
lttng start
$
lttng destroy
$
babeltrace2 ~/lttng-traces/my-user-space-session*
$
babeltrace2 /tmp/my-kernel-trace | grep _switch
$
babeltrace2 /tmp/my-kernel-trace | grep _open | wc --lines
import bt2
import sys
import collections

def top5proc():
    # Get the trace path from the first command-line argument.
    it = bt2.TraceCollectionMessageIterator(sys.argv[1])

    # This counter dictionary will hold execution times:
    #
    #     Task command name -> Total execution time (ns)
    exec_times = collections.Counter()

    # This holds the last `sched_switch` timestamp.
    last_ts = None

    for msg in it:
        # We only care about event messages.
        if type(msg) is not bt2._EventMessageConst:
            continue

        # Event of the event message.
        event = msg.event

        # Keep only `sched_switch` events.
        if event.cls.name != 'sched_switch':
            continue

        # Keep only events which occurred on CPU 0.
        if event.packet.context_field['cpu_id'] != 0:
            continue

        # Event timestamp (ns).
        cur_ts = msg.default_clock_snapshot.ns_from_origin

        if last_ts is None:
            # We start here.
            last_ts = cur_ts

        # (Short) name of the previous task command.
        prev_comm = str(event.payload_field['prev_comm'])

        # Initialize an entry in our dictionary if not yet done.
        if prev_comm not in exec_times:
            exec_times[prev_comm] = 0

        # Compute previous command execution time.
        diff = cur_ts - last_ts

        # Update execution time of this command.
        exec_times[prev_comm] += diff

        # Update last timestamp.
        last_ts = cur_ts

    # Print top 5.
    for name, ns in exec_times.most_common(5):
        print('{:20}{} s'.format(name, ns / 1e9))

if __name__ == '__main__':
    top5proc()

$
python3 top5proc.py /tmp/my-kernel-trace/kernel
swapper/0           48.607245889 s
chromium            7.192738188 s
pavucontrol         0.709894415 s
Compositor          0.660867933 s
Xorg.bin            0.616753786 s
$
lttng <GENERAL OPTIONS> <COMMAND> <COMMAND OPTIONS>
#include <lttng/lttng.h>

#undef TRACEPOINT_PROVIDER
#define TRACEPOINT_PROVIDER provider_name

#undef TRACEPOINT_INCLUDE
#define TRACEPOINT_INCLUDE "./tp.h"

#if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
#define _TP_H

#include <lttng/tracepoint.h>

/*
 * Use TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
 * TRACEPOINT_EVENT_INSTANCE(), and TRACEPOINT_LOGLEVEL() here.
 */

#endif /* _TP_H */

#include <lttng/tracepoint-event.h>

TRACEPOINT_EVENT(
    /* Tracepoint provider name */
    provider_name,

    /* Tracepoint name */
    tracepoint_name,

    /* Input arguments */
    TP_ARGS(
        arguments
    ),

    /* Output event fields */
    TP_FIELDS(
        fields
    )
)

TP_ARGS(
    type, arg_name
)

TP_ARGS(
    int, count,
    float, ratio,
    const char*, query
)

#include "my-custom-structure.h"

TRACEPOINT_EVENT(
    my_provider,
    my_tracepoint,
    TP_ARGS(
        const struct my_custom_structure*, my_custom_structure,
        float, ratio,
        const char*, query
    ),
    TP_FIELDS(
        ctf_string(query_field, query)
        ctf_float(double, ratio_field, ratio)
        ctf_integer(int, recv_size, my_custom_structure->recv_size)
        ctf_integer(int, send_size, my_custom_structure->send_size)
    )
)

tracepoint(my_provider, my_tracepoint,
           my_structure, some_ratio, the_query);

TRACEPOINT_EVENT(
    my_app,
    get_account,
    TP_ARGS(
        int, userid,
        size_t, len
    ),
    TP_FIELDS(
        ctf_integer(int, userid, userid)
        ctf_integer(size_t, len, len)
    )
)

TRACEPOINT_EVENT(
    my_app,
    get_settings,
    TP_ARGS(
        int, userid,
        size_t, len
    ),
    TP_FIELDS(
        ctf_integer(int, userid, userid)
        ctf_integer(size_t, len, len)
    )
)

TRACEPOINT_EVENT(
    my_app,
    get_transaction,
    TP_ARGS(
        int, userid,
        size_t, len
    ),
    TP_FIELDS(
        ctf_integer(int, userid, userid)
        ctf_integer(size_t, len, len)
    )
)

/* The tracepoint class */
TRACEPOINT_EVENT_CLASS(
    /* Tracepoint provider name */
    my_app,

    /* Tracepoint class name */
    my_class,

    /* Input arguments */
    TP_ARGS(
        int, userid,
        size_t, len
    ),

    /* Output event fields */
    TP_FIELDS(
        ctf_integer(int, userid, userid)
        ctf_integer(size_t, len, len)
    )
)

/* The tracepoint instances */
TRACEPOINT_EVENT_INSTANCE(
    /* Tracepoint provider name */
    my_app,

    /* Tracepoint class name */
    my_class,

    /* Tracepoint name */
    get_account,

    /* Input arguments */
    TP_ARGS(
        int, userid,
        size_t, len
    )
)
TRACEPOINT_EVENT_INSTANCE(
    my_app,
    my_class,
    get_settings,
    TP_ARGS(
        int, userid,
        size_t, len
    )
)
TRACEPOINT_EVENT_INSTANCE(
    my_app,
    my_class,
    get_transaction,
    TP_ARGS(
        int, userid,
        size_t, len
    )
)

TRACEPOINT_LOGLEVEL(provider_name, tracepoint_name, log_level)

/* Tracepoint definition */
TRACEPOINT_EVENT(
    my_app,
    get_transaction,
    TP_ARGS(
        int, userid,
        size_t, len
    ),
    TP_FIELDS(
        ctf_integer(int, userid, userid)
        ctf_integer(size_t, len, len)
    )
)

/* Log level assignment */
TRACEPOINT_LOGLEVEL(my_app, get_transaction, TRACE_DEBUG_UNIT)

#define TRACEPOINT_CREATE_PROBES

#include "tp.h"

#include "my-custom-structure.h"

TRACEPOINT_EVENT(
    my_provider,
    my_tracepoint,
    TP_ARGS(
        int, argc,
        const char*, cmd_name
    ),
    TP_FIELDS(
        ctf_string(cmd_name, cmd_name)
        ctf_integer(int, number_of_args, argc)
    )
)

#include "tp.h"

int main(int argc, char* argv[])
{
    tracepoint(my_provider, my_tracepoint, argc, argv[0]);

    return 0;
}

/* For `struct stat` */
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>

TRACEPOINT_EVENT(
    my_provider,
    my_tracepoint,
    TP_ARGS(
        int, my_int_arg,
        char*, my_str_arg,
        struct stat*, st
    ),
    TP_FIELDS(
        ctf_integer(int, my_constant_field, 23 + 17)
        ctf_integer(int, my_int_arg_field, my_int_arg)
        ctf_integer(int, my_int_arg_field2, my_int_arg * my_int_arg)
        ctf_integer(int, sum4_field, my_str_arg[0] + my_str_arg[1] +
                                     my_str_arg[2] + my_str_arg[3])
        ctf_string(my_str_arg_field, my_str_arg)
        ctf_integer_hex(off_t, size_field, st->st_size)
        ctf_float(double, size_dbl_field, (double) st->st_size)
        ctf_sequence_text(char, half_my_str_arg_field, my_str_arg,
                          size_t, strlen(my_str_arg) / 2)
    )
)

#define TRACEPOINT_DEFINE
#include "tp.h"

int main(void)
{
    struct stat s;

    stat("/etc/fstab", &s);
    tracepoint(my_provider, my_tracepoint, 23, "Hello, World!", &s);

    return 0;
}

tracepoint_enabled(provider_name, tracepoint_name)
do_tracepoint(provider_name, tracepoint_name, ...)

if (tracepoint_enabled(my_provider, my_tracepoint)) {
    stuff = prepare_stuff();
}

tracepoint(my_provider, my_tracepoint, stuff);

$
gcc -I. -c tpp.c
#define TRACEPOINT_DEFINE

$
gcc -c app.c
$
gcc -o app app.o tpp.o -llttng-ust -ldl
$
./app
$
gcc -I. -c tpp.c
$
ar rcs tpp.a tpp.o
#define TRACEPOINT_DEFINE

$
gcc -c app.c
$
gcc -o app app.o tpp.a -llttng-ust -ldl
$
./app
$
gcc -I. -fpic -c tpp.c
$
gcc -shared -o libtpp.so tpp.o -llttng-ust -ldl
#define TRACEPOINT_DEFINE

$
gcc -c app.c
$
gcc -o app app.o -ldl -L. -ltpp
$
./app
$
gcc -I. -fpic -c tpp.c
$
gcc -shared -o libtpp.so tpp.o -llttng-ust -ldl
#define TRACEPOINT_DEFINE
#define TRACEPOINT_PROBE_DYNAMIC_LINKAGE

$
gcc -c app.c
$
gcc -o app app.o -ldl
$
LD_PRELOAD=./libtpp.so ./app
$
./app
$
gcc -I. -fpic -c tpp.c
$
gcc -shared -o libtpp.so tpp.o -llttng-ust -ldl
#define TRACEPOINT_DEFINE
#define TRACEPOINT_PROBE_DYNAMIC_LINKAGE

$
gcc -c app.c
$
gcc -o app app.o -ldl
$
./app
$
gcc -I. -fpic -c tpp.c
#define TRACEPOINT_DEFINE

$
gcc -I. -fpic -c emon.c
$
gcc -shared -o libemon.so emon.o tpp.o -llttng-ust -ldl
$
gcc -c app.c
$
gcc -o app app.o -L. -lemon
$
./app
$
gcc -I. -fpic -c tpp.c
$
gcc -shared -o libtpp.so tpp.o -llttng-ust -ldl
#define TRACEPOINT_DEFINE

$
gcc -I. -fpic -c emon.c
$
gcc -shared -o libemon.so emon.o -ldl -L. -ltpp
$
gcc -c app.c
$
gcc -o app app.o -L. -lemon
$
./app
$
gcc -I. -fpic -c tpp.c
$
gcc -shared -o libtpp.so tpp.o -llttng-ust -ldl
#define TRACEPOINT_DEFINE
#define TRACEPOINT_PROBE_DYNAMIC_LINKAGE

$
gcc -I. -fpic -c emon.c
$
gcc -shared -o libemon.so emon.o -ldl
$
gcc -c app.c
$
gcc -o app app.o -L. -lemon
$
LD_PRELOAD=./libtpp.so ./app
$
./app
$
gcc -I. -fpic -c tpp.c
$
gcc -shared -o libtpp.so tpp.o -llttng-ust -ldl
#define TRACEPOINT_DEFINE
#define TRACEPOINT_PROBE_DYNAMIC_LINKAGE

$
gcc -I. -fpic -c emon.c
$
gcc -shared -o libemon.so emon.o -ldl
$
gcc -c app.c
$
gcc -o app app.o -L. -lemon
$
./app
$
gcc -I. -fpic -c tpp.c
$
gcc -shared -o libtpp.so tpp.o -llttng-ust -ldl
#define TRACEPOINT_DEFINE

$
gcc -I. -fpic -c emon.c
$
gcc -shared -o libemon.so emon.o -ldl -L. -ltpp
$
gcc -c app.c
$
gcc -o app app.o -ldl -L. -lemon
$
./app
$
gcc -I. -fpic -c tpp.c
$
gcc -shared -o libtpp.so tpp.o -llttng-ust -ldl
#define TRACEPOINT_DEFINE
#define TRACEPOINT_PROBE_DYNAMIC_LINKAGE

$
gcc -I. -fpic -c emon.c
$
gcc -shared -o libemon.so emon.o -ldl
$
gcc -c app.c
$
gcc -o app app.o -ldl -L. -lemon
$
./app
$
gcc -I. -fpic -c tpp.c
$
gcc -shared -o libtpp.so tpp.o -llttng-ust -ldl
#define TRACEPOINT_DEFINE
#define TRACEPOINT_PROBE_DYNAMIC_LINKAGE

$
gcc -I. -fpic -c emon.c
$
gcc -shared -o libemon.so emon.o -ldl
$
gcc -c app.c
$
gcc -o app app.o -L. -lemon
$
LD_PRELOAD=./libtpp.so ./app
$
./app
$
gcc -I. -c tpp.c
#define TRACEPOINT_DEFINE

$
gcc -I. -fpic -c emon.c
$
gcc -shared -o libemon.so emon.o
$
gcc -c app.c
$
gcc -o app app.o tpp.o -llttng-ust -ldl -L. -lemon
$
./app
$
gcc -I. -c tpp.c
#define TRACEPOINT_DEFINE

$
gcc -c app.c
$

gcc -Wl,--export-dynamic -o app app.o tpp.o \
  -llttng-ust -ldl
$
gcc -I. -fpic -c emon.c
$
gcc -shared -o libemon.so emon.o
$
./app
$
LD_PRELOAD=liblttng-ust-fork.so ./my-app
$
LD_PRELOAD=liblttng-ust-fork.so:/path/to/tp.so ./my-app
$
LD_PRELOAD=liblttng-ust-fd.so ./my-app
$
gcc -o my-app my-app.o tp.o $(pkg-config --cflags --libs lttng-ust)
$

cd $(mktemp -d) &&
wget http://lttng.org/files/urcu/userspace-rcu-latest-0.9.tar.bz2 &&
tar -xf userspace-rcu-latest-0.9.tar.bz2 &&
cd userspace-rcu-0.9.* &&
./configure --libdir=/usr/local/lib32 CFLAGS=-m32 &&
make &&
sudo make install &&
sudo ldconfig
$

cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-ust/lttng-ust-latest-2.12.tar.bz2 &&
tar -xf lttng-ust-latest-2.12.tar.bz2 &&
cd lttng-ust-2.12.* &&
./configure --libdir=/usr/local/lib32 \
          CFLAGS=-m32 CXXFLAGS=-m32 \
          LDFLAGS='-L/usr/local/lib32 -L/usr/lib32' &&
make &&
sudo make install &&
sudo ldconfig
$
LDFLAGS='-L/usr/lib/i386-linux-gnu -L/usr/lib32'
$

cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-tools/lttng-tools-latest-2.12.tar.bz2 &&
tar -xf lttng-tools-latest-2.12.tar.bz2 &&
cd lttng-tools-2.12.* &&
./configure --libdir=/usr/local/lib32 CFLAGS=-m32 CXXFLAGS=-m32 \
          LDFLAGS='-L/usr/local/lib32 -L/usr/lib32' \
          --disable-bin-lttng --disable-bin-lttng-crash \
          --disable-bin-lttng-relayd --disable-bin-lttng-sessiond &&
make &&
cd src/bin/lttng-consumerd &&
sudo make install &&
sudo ldconfig
$

cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-tools/lttng-tools-latest-2.12.tar.bz2 &&
tar -xf lttng-tools-latest-2.12.tar.bz2 &&
cd lttng-tools-2.12.* &&
./configure --with-consumerd32-libdir=/usr/local/lib32 \
          --with-consumerd32-bin=/usr/local/lib32/lttng/libexec/lttng-consumerd &&
make &&
sudo make install &&
sudo ldconfig
-m32 -L/usr/lib32 -L/usr/local/lib32 \
-Wl,-rpath,/usr/lib32,-rpath,/usr/local/lib32
$
$
$

gcc -m32 -c -I. hello-tp.c
gcc -m32 -c hello.c
gcc -m32 -o hello hello.o hello-tp.o \
  -L/usr/lib32 -L/usr/local/lib32 \
  -Wl,-rpath,/usr/lib32,-rpath,/usr/local/lib32 \
  -llttng-ust -ldl
#include <lttng/tracef.h>

    /* ... */

    tracef("my message: %d (%s)", my_integer, my_string);

    /* ... */

$
gcc -o app app.c -llttng-ust
$
lttng enable-event --userspace 'lttng_ust_tracef:*'
#include <lttng/tracelog.h>

    /* ... */

    tracelog(TRACE_WARNING, "my message: %d (%s)",
             my_integer, my_string);

    /* ... */

$
gcc -o app app.c -llttng-ust
$

lttng enable-event --userspace 'lttng_ust_tracelog:*'
                 --loglevel=TRACE_WARNING
$

lttng enable-event --userspace 'lttng_ust_tracelog:*'
                 --loglevel-only=TRACE_INFO
$
LD_PRELOAD=liblttng-ust-libc-wrapper.so my-app
$
LD_PRELOAD=liblttng-ust-libc-wrapper.so:liblttng-ust-dl.so my-app
import org.lttng.ust.agent.jul.LttngLogHandler;

Handler lttngUstLogHandler = new LttngLogHandler();

Logger myLogger = Logger.getLogger("some-logger");

myLogger.addHandler(lttngUstLogHandler);

myLogger.removeHandler(lttngUstLogHandler);
lttngUstLogHandler.close();

import java.io.IOException;
import java.util.logging.Handler;
import java.util.logging.Logger;
import org.lttng.ust.agent.jul.LttngLogHandler;

public class Test
{
    private static final int answer = 42;

    public static void main(String[] argv) throws Exception
    {
        // Create a logger
        Logger logger = Logger.getLogger("jello");

        // Create an LTTng-UST log handler
        Handler lttngUstLogHandler = new LttngLogHandler();

        // Add the LTTng-UST log handler to our logger
        logger.addHandler(lttngUstLogHandler);

        // Log at will!
        logger.info("some info");
        logger.warning("some warning");
        Thread.sleep(500);
        logger.finer("finer information; the answer is " + answer);
        Thread.sleep(123);
        logger.severe("error!");

        // Not mandatory, but cleaner
        logger.removeHandler(lttngUstLogHandler);
        lttngUstLogHandler.close();
    }
}

$
javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar Test.java
$
$
$
lttng create
lttng enable-event --jul jello
lttng start
$
java -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar:. Test
$
$
lttng stop
lttng view
import org.lttng.ust.agent.log4j.LttngLogAppender;

Appender lttngUstLogAppender = new LttngLogAppender();

Logger myLogger = Logger.getLogger("some-logger");

myLogger.addAppender(lttngUstLogAppender);

myLogger.removeAppender(lttngUstLogAppender);
lttngUstLogAppender.close();

import org.apache.log4j.Appender;
import org.apache.log4j.Logger;
import org.lttng.ust.agent.log4j.LttngLogAppender;

public class Test
{
    private static final int answer = 42;

    public static void main(String[] argv) throws Exception
    {
        // Create a logger
        Logger logger = Logger.getLogger("jello");

        // Create an LTTng-UST log appender
        Appender lttngUstLogAppender = new LttngLogAppender();

        // Add the LTTng-UST log appender to our logger
        logger.addAppender(lttngUstLogAppender);

        // Log at will!
        logger.info("some info");
        logger.warn("some warning");
        Thread.sleep(500);
        logger.debug("debug information; the answer is " + answer);
        Thread.sleep(123);
        logger.fatal("error!");

        // Not mandatory, but cleaner
        logger.removeAppender(lttngUstLogAppender);
        lttngUstLogAppender.close();
    }
}

$
javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-log4j.jar:$LOG4JPATH Test.java
$
$
$
lttng create
lttng enable-event --log4j jello
lttng start
$
java -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-log4j.jar:$LOG4JPATH:. Test
$
$
lttng stop
lttng view
import org.lttng.ust.agent.context.ContextInfoManager;
import org.lttng.ust.agent.context.IContextInfoRetriever;

class MyContextInfoRetriever implements IContextInfoRetriever
{
    @Override
    public Object retrieveContextInfo(String key)
    {
        if (key.equals("intCtx")) {
            return (short) 17;
        } else if (key.equals("strContext")) {
            return "context value!";
        } else {
            return null;
        }
    }
}

IContextInfoRetriever cir = new MyContextInfoRetriever();
ContextInfoManager cim = ContextInfoManager.getInstance();
cim.registerContextInfoRetriever("retrieverName", cir);

ContextInfoManager cim = ContextInfoManager.getInstance();
cim.unregisterContextInfoRetriever("retrieverName");

import java.util.logging.Handler;
import java.util.logging.Logger;
import org.lttng.ust.agent.jul.LttngLogHandler;
import org.lttng.ust.agent.context.ContextInfoManager;
import org.lttng.ust.agent.context.IContextInfoRetriever;

public class Test
{
    // Our context information retriever class
    private static class MyContextInfoRetriever
    implements IContextInfoRetriever
    {
        @Override
        public Object retrieveContextInfo(String key) {
            if (key.equals("intCtx")) {
                return (short) 17;
            } else if (key.equals("strContext")) {
                return "context value!";
            } else {
                return null;
            }
        }
    }

    private static final int answer = 42;

    public static void main(String args[]) throws Exception
    {
        // Get the context information manager instance
        ContextInfoManager cim = ContextInfoManager.getInstance();

        // Create and register our context information retriever
        IContextInfoRetriever cir = new MyContextInfoRetriever();
        cim.registerContextInfoRetriever("myRetriever", cir);

        // Create a logger
        Logger logger = Logger.getLogger("jello");

        // Create an LTTng-UST log handler
        Handler lttngUstLogHandler = new LttngLogHandler();

        // Add the LTTng-UST log handler to our logger
        logger.addHandler(lttngUstLogHandler);

        // Log at will!
        logger.info("some info");
        logger.warning("some warning");
        Thread.sleep(500);
        logger.finer("finer information; the answer is " + answer);
        Thread.sleep(123);
        logger.severe("error!");

        // Not mandatory, but cleaner
        logger.removeHandler(lttngUstLogHandler);
        lttngUstLogHandler.close();
        cim.unregisterContextInfoRetriever("myRetriever");
    }
}

$
javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar Test.java
$
$
lttng create
lttng enable-event --jul jello
$
$
lttng add-context --jul --type='$app.myRetriever:intCtx'
lttng add-context --jul --type='$app.myRetriever:strContext'
$
lttng start
$
java -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar:. Test
$
$
lttng stop
lttng view
import lttngust

import lttngust
import logging
import time

def example():
    logging.basicConfig()
    logger = logging.getLogger('my-logger')

    while True:
        logger.debug('debug message')
        logger.info('info message')
        logger.warn('warn message')
        logger.error('error message')
        logger.critical('critical message')
        time.sleep(1)

if __name__ == '__main__':
    example()

$
$
$
lttng create
lttng enable-event --python my-logger
lttng start
$
python test.py
$
$
lttng stop
lttng view
$
echo "Some message, some $variable" > /dev/lttng-logger
echo 'Hello, World!' > /dev/lttng-logger
sleep 2
df --human-readable --print-type / > /dev/lttng-logger

$
$
$
lttng create
lttng enable-event --kernel lttng_logger
lttng start
$
bash test.bash
$
$
lttng stop
lttng view
$

cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-modules/lttng-modules-latest-2.12.tar.bz2 &&
tar -xf lttng-modules-latest-2.12.tar.bz2 &&
cd lttng-modules-2.12.*
#undef TRACE_SYSTEM
#define TRACE_SYSTEM my_subsys

#if !defined(_LTTNG_MY_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ)
#define _LTTNG_MY_SUBSYS_H

#include "../../../probes/lttng-tracepoint-event.h"
#include <linux/tracepoint.h>

LTTNG_TRACEPOINT_EVENT(
    /*
     * Format is identical to the TRACE_EVENT() version for the three
     * following macro parameters:
     */
    my_subsys_my_event,
    TP_PROTO(int my_int, const char *my_string),
    TP_ARGS(my_int, my_string),

    /* LTTng-modules specific macros */
    TP_FIELDS(
        ctf_integer(int, my_int_field, my_int)
        ctf_string(my_bar_field, my_bar)
    )
)

#endif /* !defined(_LTTNG_MY_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ) */

#include "../../../probes/define_trace.h"

#include <linux/module.h>
#include "../lttng-tracer.h"

/*
 * Build-time verification of mismatch between mainline
 * TRACE_EVENT() arguments and the LTTng-modules adaptation
 * layer LTTNG_TRACEPOINT_EVENT() arguments.
 */
#include <trace/events/my_subsys.h>

/* Create LTTng tracepoint probes */
#define LTTNG_PACKAGE_BUILD
#define CREATE_TRACE_POINTS
#define TRACE_INCLUDE_PATH ../instrumentation/events/lttng-module

#include "../instrumentation/events/lttng-module/my_subsys.h"

MODULE_LICENSE("GPL and additional rights");
MODULE_AUTHOR("Your name <your-email>");
MODULE_DESCRIPTION("LTTng my_subsys probes");
MODULE_VERSION(__stringify(LTTNG_MODULES_MAJOR_VERSION) "."
    __stringify(LTTNG_MODULES_MINOR_VERSION) "."
    __stringify(LTTNG_MODULES_PATCHLEVEL_VERSION)
    LTTNG_MODULES_EXTRAVERSION);

# ...

obj-m += lttng-probe-module.o
obj-m += lttng-probe-power.o

obj-m += lttng-probe-my-subsys.o

# ...

$
#
make KERNELDIR=/path/to/linux
make modules_install && depmod -a
LTTNG_TRACEPOINT_EVENT_CODE(
    /*
     * Format identical to the LTTNG_TRACEPOINT_EVENT()
     * version for the following three macro parameters:
     */
    my_subsys_my_event,
    TP_PROTO(int my_int, const char *my_string),
    TP_ARGS(my_int, my_string),

    /* Declarations of custom local variables */
    TP_locvar(
        int a = 0;
        unsigned long b = 0;
        const char *name = "(undefined)";
        struct my_struct *my_struct;
    ),

    /*
     * Custom code which uses both tracepoint arguments
     * (in TP_ARGS()) and local variables (in TP_locvar()).
     *
     * Local variables are actually members of a structure pointed
     * to by the special variable tp_locvar.
     */
    TP_code(
        if (my_int) {
            tp_locvar->a = my_int + 17;
            tp_locvar->my_struct = get_my_struct_at(tp_locvar->a);
            tp_locvar->b = my_struct_compute_b(tp_locvar->my_struct);
            tp_locvar->name = my_struct_get_name(tp_locvar->my_struct);
            put_my_struct(tp_locvar->my_struct);

            if (tp_locvar->b) {
                tp_locvar->a = 1;
            }
        }
    ),

    /*
     * Format identical to the LTTNG_TRACEPOINT_EVENT()
     * version for this, except that tp_locvar members can be
     * used in the argument expression parameters of
     * the ctf_*() macros.
     */
    TP_FIELDS(
        ctf_integer(unsigned long, my_struct_b, tp_locvar->b)
        ctf_integer(int, my_struct_a, tp_locvar->a)
        ctf_string(my_string_field, my_string)
        ctf_string(my_struct_name, tp_locvar->name)
    )
)

#
lttng-sessiond --extra-kmod-probes=my_subsys,usb
#
lttng-sessiond --kmod-probes=my_subsys,usb
$
lsmod | grep lttng_probe_usb
#
pkill lttng-sessiond
Error: No session daemon is available
$
lttng-sessiond --daemonize
#
lttng-sessiond --daemonize
$
lttng create
$
lttng create my-session
$
lttng create my-session --output=/tmp/some-directory
$
lttng list
$
lttng set-session new-session
$
lttng destroy
$
lttng list --userspace
$
lttng list --kernel --syscall
$
lttng enable-event --kernel sched_switch
$
lttng enable-event --kernel --syscall open,write,read,close
$
lttng enable-event --kernel sched_switch --filter='prev_comm == "bash"'
$

lttng enable-event --kernel --all \
                 --filter='$ctx.tid == 1988 || $ctx.tid == 1534'
$

lttng enable-event --jul my_logger \
                 --filter='$app.retriever:cur_msg_id > 3'
$
lttng enable-event --userspace my_app:'*' --loglevel=TRACE_INFO
$

lttng enable-event --python my-app.'*' \
                 --exclude='my-app.module,my-app.hello'
$
lttng enable-event --log4j --all --loglevel-only=LOG4J_WARN
$
lttng enable-event --userspace my_app:my_tracepoint --channel=my-channel
$

lttng enable-event --kernel --userspace-probe=/usr/lib/libc.so.6:malloc \
                 libc_malloc
$

lttng enable-event --kernel --userspace-probe=sdt:serv:server:accept_request \
                server_accept_request
$
$

lttng enable-event --userspace my_app:my_tracepoint
lttng enable-event --userspace my_app:my_tracepoint \
                 --loglevel=TRACE_INFO
$
lttng disable-event --python my-logger
$
lttng disable-event --jul '*'
$
lttng disable-event --jul --all-events
$
lttng status
$
lttng list my-session
$
lttng start
$
lttng stop
$
lttng clear
$
lttng clear --all
$
lttng enable-channel --kernel my-channel
$

lttng enable-channel --userspace --num-subbuf=4 --subbuf-size=1M \
                   --buffers-pid my-channel
$
$
$
$
lttng create
lttng enable-channel --userspace --blocking-timeout=inf blocking-channel
lttng enable-event --userspace --channel=blocking-channel --all
lttng start
$
LTTNG_UST_ALLOW_BLOCKING=1 my-app
$

lttng enable-channel --kernel --tracefile-count=8 \
                   --tracefile-size=4194304 my-channel
$
lttng enable-channel --userspace --overwrite my-channel
$
$
lttng enable-event --userspace --channel=my-channel app:tp
lttng enable-event --userspace --channel=other-channel app:tp
$
lttng disable-channel --kernel my-channel
$
lttng add-context --userspace --type=vpid --type=perf:thread:cpu-cycles
$
$
lttng add-context --userspace --type=perf:thread:raw:r0110:test
lttng add-context --kernel --type=perf:cpu:raw:r0013c:x86unhalted
$

lttng add-context --kernel --channel=my-channel \
   --type=tid --type=callstack-user
$

lttng add-context --kernel --channel=my-channel \
                --type='$app:retriever:cur_msg_id'
$
lttng track --userspace --vpid=3,4,7,10,13
$
lttng track --userspace --vpid=1,15,16
$
lttng untrack --userspace --vpid=3,7,10,13
$
lttng track --userspace --vpid --all
$
lttng untrack --kernel --uid --all
$
lttng track --kernel --uid=http,11
$
lttng save my-session
$
lttng load my-session
$
lttng-relayd
$
lttng create my-session --set-url=net://remote-system
$
lttng create my-session --live
$
babeltrace2 net://localhost/host/hostname/my-session
$
babeltrace2 net://localhost
$
lttng create my-session --snapshot
$
lttng snapshot record --name=my-first-snapshot
$
lttng create my-session
$
$
lttng enable-event --kernel sched_'*'
lttng start
$
lttng rotate
$
lttng destroy
$
lttng create my-session
$
lttng enable-event --kernel sched_'*'
$
lttng enable-rotation --timer=10s
$
lttng start
$
lttng destroy
$
lttng --mi=xml enable-event --kernel --syscall open
$
lttng regenerate metadata
$
lttng regenerate statedump
$
lttng stop
$
lttng snapshot record --name=my-snapshot
$
lttng create my-session --shm-path=/path/to/shm
$
lttng-crash /path/to/shm
$
lttng-crash --extract=/path/to/trace /path/to/shm
#include <stdio.h>
#include <assert.h>
#include <lttng/domain.h>
#include <lttng/action/action.h>
#include <lttng/action/notify.h>
#include <lttng/condition/condition.h>
#include <lttng/condition/buffer-usage.h>
#include <lttng/condition/evaluation.h>
#include <lttng/notification/channel.h>
#include <lttng/notification/notification.h>
#include <lttng/trigger/trigger.h>
#include <lttng/endpoint.h>

int main(int argc, char *argv[])
{
    int exit_status = 0;
    struct lttng_notification_channel *notification_channel;
    struct lttng_condition *condition;
    struct lttng_action *action;
    struct lttng_trigger *trigger;
    const char *tracing_session_name;
    const char *channel_name;

    assert(argc >= 3);
    tracing_session_name = argv[1];
    channel_name = argv[2];

    /*
     * Create a notification channel. A notification channel
     * connects the user application to the LTTng session daemon.
     * This notification channel can be used to listen to various
     * types of notifications.
     */
    notification_channel = lttng_notification_channel_create(
        lttng_session_daemon_notification_endpoint);

    /*
     * Create a "high buffer usage" condition. In this case, the
     * condition is reached when the buffer usage is greater than or
     * equal to 75 %. We create the condition for a specific tracing
     * session name, channel name, and for the user space tracing
     * domain.
     *
     * The "low buffer usage" condition type also exists.
     */
    condition = lttng_condition_buffer_usage_high_create();
    lttng_condition_buffer_usage_set_threshold_ratio(condition, .75);
    lttng_condition_buffer_usage_set_session_name(
        condition, tracing_session_name);
    lttng_condition_buffer_usage_set_channel_name(condition,
        channel_name);
    lttng_condition_buffer_usage_set_domain_type(condition,
        LTTNG_DOMAIN_UST);

    /*
     * Create an action (get a notification) to take when the
     * condition created above is reached.
     */
    action = lttng_action_notify_create();

    /*
     * Create a trigger. A trigger associates a condition to an
     * action: the action is executed when the condition is reached.
     */
    trigger = lttng_trigger_create(condition, action);

    /* Register the trigger to LTTng. */
    lttng_register_trigger(trigger);

    /*
     * Now that we have registered a trigger, a notification will be
     * emitted everytime its condition is met. To receive this
     * notification, we must subscribe to notifications that match
     * the same condition.
     */
    lttng_notification_channel_subscribe(notification_channel,
        condition);

    /*
     * Notification loop. Put this in a dedicated thread to avoid
     * blocking the main thread.
     */
    for (;;) {
        struct lttng_notification *notification;
        enum lttng_notification_channel_status status;
        const struct lttng_evaluation *notification_evaluation;
        const struct lttng_condition *notification_condition;
        double buffer_usage;

        /* Receive the next notification. */
        status = lttng_notification_channel_get_next_notification(
            notification_channel, &notification);

        switch (status) {
        case LTTNG_NOTIFICATION_CHANNEL_STATUS_OK:
            break;
        case LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED:
            /*
             * The session daemon can drop notifications if a monitoring
             * application isn't consuming the notifications fast
             * enough.
             */
            continue;
        case LTTNG_NOTIFICATION_CHANNEL_STATUS_CLOSED:
            /*
             * The notification channel has been closed by the
             * session daemon. This is typically caused by a session
             * daemon shutting down.
             */
            goto end;
        default:
            /* Unhandled conditions or errors. */
            exit_status = 1;
            goto end;
        }

        /*
         * A notification provides, amongst other things:
         *
         * * The condition that caused this notification to be
         *   emitted.
         * * The condition evaluation, which provides more
         *   specific information on the evaluation of the
         *   condition.
         *
         * The condition evaluation provides the buffer usage
         * value at the moment the condition was reached.
         */
        notification_condition = lttng_notification_get_condition(
            notification);
        notification_evaluation = lttng_notification_get_evaluation(
            notification);

        /* We're subscribed to only one condition. */
        assert(lttng_condition_get_type(notification_condition) ==
            LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH);

        /*
         * Get the exact sampled buffer usage from the
         * condition evaluation.
         */
        lttng_evaluation_buffer_usage_get_usage_ratio(
            notification_evaluation, &buffer_usage);

        /*
         * At this point, instead of printing a message, we
         * could do something to reduce the buffer usage of the channel,
         * like disable specific events.
         */
        printf("Buffer usage is %f %% in tracing session \"%s\", "
            "user space channel \"%s\".\n", buffer_usage * 100,
            tracing_session_name, channel_name);
        lttng_notification_destroy(notification);
    }

end:
    lttng_action_destroy(action);
    lttng_condition_destroy(condition);
    lttng_trigger_destroy(trigger);
    lttng_notification_channel_destroy(notification_channel);
    return exit_status;
}

$
gcc -o notif-app notif-app.c -llttng-ctl
$
$
$
lttng create my-session
lttng enable-event --userspace --all
lttng start
$
./notif-app my-session channel0
Buffer usage is 81.45197 % in tracing session "my-session", user space
channel "channel0".
LTTNG_TRACEPOINT_ENUM(name, TP_ENUM_VALUES(entries))

LTTNG_TRACEPOINT_ENUM(
    my_enum,
    TP_ENUM_VALUES(
        ctf_enum_auto("AUTO: EXPECT 0")
        ctf_enum_value("VALUE: 23", 23)
        ctf_enum_value("VALUE: 27", 27)
        ctf_enum_auto("AUTO: EXPECT 28")
        ctf_enum_range("RANGE: 101 TO 303", 101, 303)
        ctf_enum_auto("AUTO: EXPECT 304")
    )
)

Distribution	Available in releases
Ubuntu	Ubuntu 16.04 Xenial Xerus, Ubuntu 18.04 Bionic Beaver, Ubuntu 20.04 Focal Fossa, and Ubuntu 22.04 Jammy Jellyfish: use the LTTng Stable 2.12 PPA.
Debian	Debian 11 bullseye.
RHEL and SLES	See EfficiOS Enterprise Packages.
Alpine Linux	Alpine Linux 3.12, Alpine Linux 3.13, Alpine Linux 3.14, and Alpine Linux 3.15.
Buildroot	Buildroot 2020.08, Buildroot 2020.11, Builroot 2021.02, Buildroot 2021.05, Buildroot 2021.08, and Builroot 2021.11.
OpenEmbedded and Yocto	Yocto Project 3.2 Gatesgarth and Yocto Project 3.3 Hardknott.

Field name	Field value
`my_constant_field`	40
`my_int_arg_field`	23
`my_int_arg_field2`	529
`sum4_field`	389
`my_str_arg_field`	`Hello, World!`
`size_field`	0x12d
`size_dbl_field`	301.0
`half_my_str_arg_field`	`Hello,`

TP provider name	TP name	Instrumented function
`lttng_ust_libc`	`malloc`	malloc(3)
	`calloc`	calloc(3)
	`realloc`	realloc(3)
	`free`	free(3)
	`memalign`	memalign(3)
	`posix_memalign`	posix_memalign(3)

TP provider name	TP name	Instrumented function
`lttng_ust_pthread`	`pthread_mutex_lock_req`	pthread_mutex_lock(3p) (request time)
	`pthread_mutex_lock_acq`	pthread_mutex_lock(3p) (acquire time)
	`pthread_mutex_trylock`	pthread_mutex_trylock(3p)
	`pthread_mutex_unlock`	pthread_mutex_unlock(3p)

Argument	Description	Applicable tracing domains
One of: `--syscall` `--probe=ADDR` `--function=ADDR` `--userspace-probe=PATH:SYMBOL` `--userspace-probe=sdt:PATH:PROVIDER:NAME`	Instead of using the default tracepoint instrumentation type, use: A Linux system call (entry and exit). A Linux kprobe (symbol or address). The entry and return points of a Linux function (symbol or address). The entry point of a user application or library function (path to application/library and symbol). A SystemTap Statically Defined Tracing (USDT) probe (path to application/library, provider and probe names).	Linux kernel.
First positional argument.	Tracepoint or system call name. With the `--probe`, `--function`, and `--userspace-probe` options, this is a custom name given to the event rule. With the JUL, log4j, and Python domains, this is a logger name. With a tracepoint, logger, or system call name, use the special `` globbing character to match anything (for example, `sched_`, `my_comp:msg_*`).	All.
One of: `--loglevel=LEVEL` `--loglevel-only=LEVEL`	Match only tracepoints or log statements with a logging level at least as severe as `LEVEL`. Match only tracepoints or log statements with a logging level equal to `LEVEL`. See lttng-enable-event(1) for the list of available logging level names.	User space, JUL, log4j, and Python.
`--exclude=EXCLUSIONS`	When you use a `*` character at the end of the tracepoint or logger name (first positional argument), exclude the specific names in the comma-delimited list `EXCLUSIONS`.	User space, JUL, log4j, and Python.
`--filter=EXPR`	Match only events which satisfy the expression `EXPR`. See lttng-enable-event(1) to learn more about the syntax of a filter expression.	All.

Option	Description
`--overwrite`	Use the overwrite event record loss mode instead of the default discard mode.
`--buffers-pid` (user space tracing domain only)	Use the per-process buffering scheme instead of the default per-user buffering scheme.
`--subbuf-size=SIZE`	Allocate sub-buffers of `SIZE` bytes (power of two), for each CPU, either for each Unix user (default), or for each instrumented process. See Sub-buffer count and size.
`--num-subbuf=COUNT`	Allocate `COUNT` sub-buffers (power of two), for each CPU, either for each Unix user (default), or for each instrumented process. See Sub-buffer count and size.
`--tracefile-size=SIZE`	Set the maximum size of each trace file that this channel writes within a stream to `SIZE` bytes instead of no maximum. See Trace file count and size.
`--tracefile-count=COUNT`	Limit the number of trace files that this channel creates to `COUNT` channels instead of no limit. See Trace file count and size.
`--switch-timer=PERIODUS`	Set the switch timer period to `PERIODUS` µs.
`--read-timer=PERIODUS`	Set the read timer period to `PERIODUS` µs.
`--blocking-timeout=TIMEOUTUS`	Set the timeout of user space applications which load LTTng-UST in blocking mode to `TIMEOUTUS`: 0 (default) Never block (non-blocking mode). `inf` Block forever until space is available in a sub-buffer to record the event. n, a positive value Wait for at most n µs when trying to write into a sub-buffer. Note that, for this option to have any effect on an instrumented user space application, you need to run the application with a set `LTTNG_UST_ALLOW_BLOCKING` environment variable.
`--output=TYPE` (Linux kernel tracing domain only)	Set the output type of the channel to `TYPE`, either `mmap` or `splice`.

Docs/2.12

Options

The LTTng Documentation

Welcome!

Target audience

What’s in this documentation?

Convention

Acknowledgements