NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | ENVIRONMENT VARIABLES | BUGS | RESOURCES | COPYRIGHTS | THANKS | AUTHORS | SEE ALSO | COLOPHON

LTTNG-UST(3)                    LTTng Manual                    LTTNG-UST(3)

NAME         top

       lttng-ust - LTTng user space tracing

SYNOPSIS         top

       #include <lttng/tracepoint.h>

       #define TRACEPOINT_ENUM(prov_name, enum_name, mappings)
       #define TRACEPOINT_EVENT(prov_name, t_name, args, fields)
       #define TRACEPOINT_EVENT_CLASS(prov_name, class_name, args, fields)
       #define TRACEPOINT_EVENT_INSTANCE(prov_name, class_name, t_name, args)
       #define TRACEPOINT_LOGLEVEL(prov_name, t_name, level)
       #define ctf_array(int_type, field_name, expr, count)
       #define ctf_array_nowrite(int_type, field_name, expr, count)
       #define ctf_array_hex(int_type, field_name, expr, count)
       #define ctf_array_nowrite_hex(int_type, field_name, expr, count)
       #define ctf_array_network(int_type, field_name, expr, count)
       #define ctf_array_network_nowrite(int_type, field_name, expr, count)
       #define ctf_array_network_hex(int_type, field_name, expr, count)
       #define ctf_array_network_nowrite_hex(int_type, field_name, expr, count)
       #define ctf_array_text(char, field_name, expr, count)
       #define ctf_array_text_nowrite(char, field_name, expr, count)
       #define ctf_enum(prov_name, enum_name, int_type, field_name, expr)
       #define ctf_enum_nowrite(prov_name, enum_name, int_type, field_name,
                                expr)
       #define ctf_enum_value(label, value)
       #define ctf_enum_range(label, start, end)
       #define ctf_float(float_type, field_name, expr)
       #define ctf_float_nowrite(float_type, field_name, expr)
       #define ctf_integer(int_type, field_name, expr)
       #define ctf_integer_hex(int_type, field_name, expr)
       #define ctf_integer_network(int_type, field_name, expr)
       #define ctf_integer_network_hex(int_type, field_name, expr)
       #define ctf_integer_nowrite(int_type, field_name, expr)
       #define ctf_sequence(int_type, field_name, expr, len_type, len_expr)
       #define ctf_sequence_nowrite(int_type, field_name, expr, len_type,
                                    len_expr)
       #define ctf_sequence_hex(int_type, field_name, expr, len_type,
                                len_expr)
       #define ctf_sequence_nowrite_hex(int_type, field_name, expr, len_type,
                                        len_expr)
       #define ctf_sequence_network(int_type, field_name, expr, len_type,
                                    len_expr)
       #define ctf_sequence_network_nowrite(int_type, field_name, expr,
                                            len_type, len_expr)
       #define ctf_sequence_network_hex(int_type, field_name, expr, len_type,
                                        len_expr)
       #define ctf_sequence_network_nowrite_hex(int_type, field_name, expr,
                                                len_type, len_expr)
       #define ctf_sequence_text(char, field_name, expr, len_type, len_expr)
       #define ctf_sequence_text_nowrite(char, field_name, expr, len_type,
                                         len_expr)
       #define ctf_string(field_name, expr)
       #define ctf_string_nowrite(field_name, expr)
       #define do_tracepoint(prov_name, t_name, ...)
       #define tracepoint(prov_name, t_name, ...)
       #define tracepoint_enabled(prov_name, t_name)

       Link with -llttng-ust -ldl, following this man page.

DESCRIPTION         top

       The Linux Trace Toolkit: next generation <http://lttng.org/> is an
       open source software package used for correlated tracing of the Linux
       kernel, user applications, and user libraries.

       LTTng-UST is the user space tracing component of the LTTng project.
       It is a port to user space of the low-overhead tracing capabilities
       of the LTTng Linux kernel tracer. The liblttng-ust library is used to
       trace user applications and libraries.

           Note
           This man page is about the liblttng-ust library. The LTTng-UST
           project also provides Java and Python packages to trace
           applications written in those languages. How to instrument and
           trace Java and Python applications is documented in the online
           LTTng documentation <http://lttng.org/docs/>.

       There are three ways to use liblttng-ust:

       ·   Using the tracef(3) API, which is similar to printf(3).

       ·   Using the tracelog(3) API, which is tracef(3) with a log level
           parameter.

       ·   Defining your own tracepoints. See the Creating a tracepoint
           provider section below.

   Creating a tracepoint provider
       Creating a tracepoint provider is the first step of using liblttng-
       ust. The next steps are:

       ·   Instrumenting your application with tracepoint() calls

       ·   Building your application with LTTng-UST support, either
           statically or dynamically.

       A tracepoint provider is a compiled object containing the event
       probes corresponding to your custom tracepoint definitions. A
       tracepoint provider contains the code to get the size of an event and
       to serialize it, amongst other things.

       To create a tracepoint provider, start with the following tracepoint
       provider header template:

           #undef TRACEPOINT_PROVIDER
           #define TRACEPOINT_PROVIDER my_provider

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

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

           #include <lttng/tracepoint.h>

           /*
            * TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
            * TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(),
            * and `TRACEPOINT_ENUM()` are used here.
            */

           #endif /* _TP_H */

           #include <lttng/tracepoint-event.h>

       In this template, the tracepoint provider is named my_provider
       (TRACEPOINT_PROVIDER definition). The file needs to bear the name of
       the TRACEPOINT_INCLUDE definition (tp.h in this case). Between
       #include <lttng/tracepoint.h> and #endif go the invocations of the
       TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
       TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(), and
       TRACEPOINT_ENUM() macros.

           Note
           You can avoid writing the prologue and epilogue boilerplate in
           the template file above by using the lttng-gen-tp(1) tool shipped
           with LTTng-UST.

       The tracepoint provider header file needs to be included in a source
       file which looks like this:

           #define TRACEPOINT_CREATE_PROBES

           #include "tp.h"

       Together, those two files (let’s call them tp.h and tp.c) form the
       tracepoint provider sources, ready to be compiled.

       You can create multiple tracepoint providers to be used in a single
       application, but each one must have its own header file.

       The TRACEPOINT_EVENT() usage section below shows how to use the
       TRACEPOINT_EVENT() macro to define the actual tracepoints in the
       tracepoint provider header file.

       See the EXAMPLE section below for a complete example.

   TRACEPOINT_EVENT() usage
       The TRACEPOINT_EVENT() macro is used in a template provider header
       file (see the Creating a tracepoint provider section above) to define
       LTTng-UST tracepoints.

       The TRACEPOINT_EVENT() usage template is as follows:

           TRACEPOINT_EVENT(
               /* Tracepoint provider name */
               my_provider,

               /* Tracepoint/event name */
               my_tracepoint,

               /* List of tracepoint arguments (input) */
               TP_ARGS(
                   ...
               ),

               /* List of fields of eventual event (output) */
               TP_FIELDS(
                   ...
               )
           )

       The TP_ARGS() macro contains the input arguments of the tracepoint.
       Those arguments can be used in the argument expressions of the output
       fields defined in TP_FIELDS().

       The format of the TP_ARGS() parameters is: C type, then argument
       name; repeat as needed, up to ten times. For example:

           TP_ARGS(
               int, my_int,
               const char *, my_string,
               FILE *, my_file,
               double, my_float,
               struct my_data *, my_data
           )

       The TP_FIELDS() macro contains the output fields of the tracepoint,
       that is, the actual data that can be recorded in the payload of an
       event emitted by this tracepoint.

       The TP_FIELDS() macro contains a list of ctf_*() macros NOT separated
       by commas. The available macros are documented in the Available
       ctf_*() field type macros section below.

   Available ctf_*() field type macros
       This section documents the available ctf_*() macros that can be
       inserted in the TP_FIELDS() macro of the TRACEPOINT_EVENT() macro.

       Standard integer, displayed in base 10:

           ctf_integer(int_type, field_name, expr)
           ctf_integer_nowrite(int_type, field_name, expr)

       Standard integer, displayed in base 16:

           ctf_integer_hex(int_type, field_name, expr)

       Integer in network byte order (big endian), displayed in base 10:

           ctf_integer_network(int_type, field_name, expr)

       Integer in network byte order, displayed in base 16:

           ctf_integer_network_hex(int_type, field_name, expr)

       Floating point number:

           ctf_float(float_type, field_name, expr)
           ctf_float_nowrite(float_type, field_name, expr)

       Null-terminated string:

           ctf_string(field_name, expr)
           ctf_string_nowrite(field_name, expr)

       Statically-sized array of integers (_hex versions displayed in
       hexadecimal, _network versions in network byte order):

           ctf_array(int_type, field_name, expr, count)
           ctf_array_nowrite(int_type, field_name, expr, count)
           ctf_array_hex(int_type, field_name, expr, count)
           ctf_array_nowrite_hex(int_type, field_name, expr, count)
           ctf_array_network(int_type, field_name, expr, count)
           ctf_array_network_nowrite(int_type, field_name, expr, count)
           ctf_array_network_hex(int_type, field_name, expr, count)
           ctf_array_network_nowrite_hex(int_type, field_name, expr, count)

       Statically-sized array, printed as text; no need to be
       null-terminated:

           ctf_array_text(char, field_name, expr, count)
           ctf_array_text_nowrite(char, field_name, expr, count)

       Dynamically-sized array of integers (_hex versions displayed in
       hexadecimal, _network versions in network byte order):

           ctf_sequence(int_type, field_name, expr, len_type, len_expr)
           ctf_sequence_nowrite(int_type, field_name, expr, len_type, len_expr)
           ctf_sequence_hex(int_type, field_name, expr, len_type, len_expr)
           ctf_sequence_nowrite_hex(int_type, field_name, expr, len_type,
                                    len_expr)
           ctf_sequence_network(int_type, field_name, expr, len_type, len_expr)
           ctf_sequence_network_nowrite(int_type, field_name, expr, len_type,
                                        len_expr)
           ctf_sequence_network_hex(int_type, field_name, expr, len_type,
                                    len_expr)
           ctf_sequence_network_nowrite_hex(int_type, field_name, expr,
                                            len_type, len_expr)

       Dynamically-sized array, displayed as text; no need to be
       null-terminated:

           ctf_sequence_text(char, field_name, expr, len_type, len_expr)
           ctf_sequence_text_nowrite(char, field_name, expr, len_type, len_expr)

       Enumeration. The enumeration field must be defined before using this
       macro with the TRACEPOINT_ENUM() macro. See the TRACEPOINT_ENUM()
       usage section for more information.

           ctf_enum(prov_name, enum_name, int_type, field_name, expr)
           ctf_enum_nowrite(prov_name, enum_name, int_type, field_name, expr)

       The parameters are:

       count
           Number of elements in array/sequence. This must be known at
           compile time.

       enum_name
           Name of an enumeration field previously defined with the
           TRACEPOINT_ENUM() macro. See the TRACEPOINT_ENUM() usage section
           for more information.

       expr
           C expression resulting in the field’s value. This expression can
           use one or more arguments passed to the tracepoint. The arguments
           of a given tracepoint are defined in the TP_ARGS() macro (see the
           Creating a tracepoint provider section above).

       field_name
           Event field name (C identifier syntax, NOT a literal string).

       float_type
           Float C type (float or double). The size of this type determines
           the size of the floating point number field.

       int_type
           Integer C type. The size of this type determines the size of the
           integer/enumeration field.

       len_expr
           C expression resulting in the sequence’s length. This expression
           can use one or more arguments passed to the tracepoint.

       len_type
           Unsigned integer C type of sequence’s length.

       prov_name
           Tracepoint provider name. This must be the same as the tracepoint
           provider name used in a previous field definition.

       The _nowrite versions omit themselves from the recorded trace, but
       are otherwise identical. Their primary purpose is to make some of the
       event context available to the event filters without having to commit
       the data to sub-buffers. See lttng-enable-event(1) to learn more
       about dynamic event filtering.

       See the EXAMPLE section below for a complete example.

   TRACEPOINT_ENUM() usage
       An enumeration field is a list of mappings between an integers, or a
       range of integers, and strings (sometimes called labels or
       enumerators). Enumeration fields can be used to have a more compact
       trace when the possible values for a field are limited.

       An enumeration field is defined with the TRACEPOINT_ENUM() macro:

           TRACEPOINT_ENUM(
               /* Tracepoint provider name */
               my_provider,

               /* Enumeration name (unique in the whole tracepoint provider) */
               my_enum,

               /* Enumeration mappings */
               TP_ENUM_VALUES(
                   ...
               )
           )

       TP_ENUM_VALUES() contains a list of enumeration mappings, NOT
       separated by commas. Two macros can be used in the TP_ENUM_VALUES():
       ctf_enum_value() and ctf_enum_range().

       ctf_enum_value() is a single value mapping:

           ctf_enum_value(label, value)

       This macro maps the given label string to the value value.

       ctf_enum_range() is a range mapping:

           ctf_enum_range(label, start, end)

       This macro maps the given label string to the range of integers from
       start to end, inclusively. Range mappings may overlap, but the
       behaviour is implementation-defined: each trace reader handles
       overlapping ranges as it wishes.

       See the EXAMPLE section below for a complete example.

   TRACEPOINT_EVENT_CLASS() usage
       A tracepoint class is a class of tracepoints sharing the same field
       types and names. A tracepoint instance is one instance of such a
       declared tracepoint class, with its own event name.

       LTTng-UST creates one event serialization function per tracepoint
       class. Using TRACEPOINT_EVENT() creates one tracepoint class per
       tracepoint definition, whereas using TRACEPOINT_EVENT_CLASS() and
       TRACEPOINT_EVENT_INSTANCE() creates one tracepoint class, and one or
       more tracepoint instances of this class. In other words, many
       tracepoints can reuse the same serialization code. Reusing the same
       code, when possible, can reduce cache pollution, thus improve
       performance.

       The TRACEPOINT_EVENT_CLASS() macro accepts the same parameters as the
       TRACEPOINT_EVENT() macro, except that instead of an event name, its
       second parameter is the tracepoint class name:

           TRACEPOINT_EVENT_CLASS(
               /* Tracepoint provider name */
               my_provider,

               /* Tracepoint class name */
               my_tracepoint_class,

               /* List of tracepoint arguments (input) */
               TP_ARGS(
                   ...
               ),

               /* List of fields of eventual event (output) */
               TP_FIELDS(
                   ...
               )
           )

       Once the tracepoint class is defined, you can create as many
       tracepoint instances as needed:

           TRACEPOINT_EVENT_INSTANCE(
               /* Tracepoint provider name */
               my_provider,

               /* Tracepoint class name */
               my_tracepoint_class,

               /* Tracepoint/event name */
               my_tracepoint,

               /* List of tracepoint arguments (input) */
               TP_ARGS(
                   ...
               )
           )

       As you can see, the TRACEPOINT_EVENT_INSTANCE() does not contain the
       TP_FIELDS() macro, because they are defined at the
       TRACEPOINT_EVENT_CLASS() level.

       See the EXAMPLE section below for a complete example.

   TRACEPOINT_LOGLEVEL() usage
       Optionally, a log level can be assigned to a defined tracepoint.
       Assigning different levels of severity to tracepoints can be useful:
       when controlling tracing sessions, you can choose to only enable
       events falling into a specific log level range using the --loglevel
       and --loglevel-only options of the lttng-enable-event(1) command.

       Log levels are assigned to tracepoints that are already defined using
       the TRACEPOINT_LOGLEVEL() macro. The latter must be used after having
       used TRACEPOINT_EVENT() or TRACEPOINT_EVENT_INSTANCE() for a given
       tracepoint. The TRACEPOINT_LOGLEVEL() macro is used as follows:

           TRACEPOINT_LOGLEVEL(
               /* Tracepoint provider name */
               my_provider,

               /* Tracepoint/event name */
               my_tracepoint,

               /* Log level */
               TRACE_INFO
           )

       The available log level definitions are:

       TRACE_EMERG
           System is unusable.

       TRACE_ALERT
           Action must be taken immediately.

       TRACE_CRIT
           Critical conditions.

       TRACE_ERR
           Error conditions.

       TRACE_WARNING
           Warning conditions.

       TRACE_NOTICE
           Normal, but significant, condition.

       TRACE_INFO
           Informational message.

       TRACE_DEBUG_SYSTEM
           Debug information with system-level scope (set of programs).

       TRACE_DEBUG_PROGRAM
           Debug information with program-level scope (set of processes).

       TRACE_DEBUG_PROCESS
           Debug information with process-level scope (set of modules).

       TRACE_DEBUG_MODULE
           Debug information with module (executable/library) scope (set of
           units).

       TRACE_DEBUG_UNIT
           Debug information with compilation unit scope (set of functions).

       TRACE_DEBUG_FUNCTION
           Debug information with function-level scope.

       TRACE_DEBUG_LINE
           Debug information with line-level scope (default log level).

       TRACE_DEBUG
           Debug-level message.

       See the EXAMPLE section below for a complete example.

   Instrumenting your application
       Once the tracepoint provider is created (see the Creating a
       tracepoint provider section above), you can instrument your
       application with the defined tracepoints thanks to the tracepoint()
       macro:

           #define tracepoint(prov_name, t_name, ...)

       With:

       prov_name
           Tracepoint provider name.

       t_name
           Tracepoint/event name.

       ...
           Tracepoint arguments, if any.

       Make sure to include the tracepoint provider header file anywhere you
       use tracepoint() for this provider.

           Note
           Even though LTTng-UST supports tracepoint() call site duplicates
           having the same provider and tracepoint names, it is recommended
           to use a provider/tracepoint name pair only once within the
           application source code to help map events back to their call
           sites when analyzing the trace.

       Sometimes, arguments to the tracepoint are expensive to compute (take
       call stack, for example). To avoid the computation when the
       tracepoint is disabled, you can use the tracepoint_enabled() and
       do_tracepoint() macros:

           #define tracepoint_enabled(prov_name, t_name)
           #define do_tracepoint(prov_name, t_name, ...)

       tracepoint_enabled() returns a non-zero value if the tracepoint named
       t_name from the provider named prov_name is enabled at run time.

       do_tracepoint() is like tracepoint(), except that it doesn’t check if
       the tracepoint is enabled. Using tracepoint() with
       tracepoint_enabled() is dangerous since tracepoint() also contains
       the tracepoint_enabled() check, thus a race condition is possible in
       this situation:

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

           tracepoint(my_provider, my_tracepoint, stuff);

       If the tracepoint is enabled after the condition, then stuff is not
       prepared: the emitted event will either contain wrong data, or the
       whole application could crash (segmentation fault, for example).

           Note
           Neither tracepoint_enabled() nor do_tracepoint() have a
           STAP_PROBEV() call, so if you need it, you should emit this call
           yourself.

   Statically linking the tracepoint provider
       With the static linking method, compiled tracepoint providers are
       copied into the target application.

       Define TRACEPOINT_DEFINE definition below the
       TRACEPOINT_CREATE_PROBES definition in the tracepoint provider
       source:

           #define TRACEPOINT_CREATE_PROBES
           #define TRACEPOINT_DEFINE

           #include "tp.h"

       Create the tracepoint provider object file:

           $ cc -c -I. tp.c

           Note
           Although an application instrumented with LTTng-UST tracepoints
           can be compiled with a C++ compiler, tracepoint probes should be
           compiled with a C compiler.

       At this point, you can archive this tracepoint provider object file,
       possibly with other object files of your application or with other
       tracepoint provider object files, as a static library:

           $ ar rc tp.a tp.o

       Using a static library does have the advantage of centralising the
       tracepoint providers objects so they can be shared between multiple
       applications. This way, when the tracepoint provider is modified, the
       source code changes don’t have to be patched into each application’s
       source code tree. The applications need to be relinked after each
       change, but need not to be otherwise recompiled (unless the
       tracepoint provider’s API changes).

       Then, link your application with this object file (or with the static
       library containing it) and with liblttng-ust and libdl (libc on a BSD
       system):

           $ cc -o app tp.o app.o -llttng-ust -ldl

   Dynamically loading the tracepoint provider
       The second approach to package the tracepoint provider is to use the
       dynamic loader: the library and its member functions are explicitly
       sought, loaded at run time.

       In this scenario, the tracepoint provider is compiled as a shared
       object.

       The process to create the tracepoint provider shared object is pretty
       much the same as the static linking method, except that:

       ·   Since the tracepoint provider is not part of the application,
           TRACEPOINT_DEFINE must be defined, for each tracepoint provider,
           in exactly one source file of the application

       ·   TRACEPOINT_PROBE_DYNAMIC_LINKAGE must be defined next to
           TRACEPOINT_DEFINE

       Regarding TRACEPOINT_DEFINE and TRACEPOINT_PROBE_DYNAMIC_LINKAGE, the
       recommended practice is to use a separate C source file in your
       application to define them, then include the tracepoint provider
       header files afterwards. For example, as tp-define.c:

           #define TRACEPOINT_DEFINE
           #define TRACEPOINT_PROBE_DYNAMIC_LINKAGE

           #include "tp.h"

       The tracepoint provider object file used to create the shared library
       is built like it is using the static linking method, but with the
       -fpic option:

           $ cc -c -fpic -I. tp.c

       It is then linked as a shared library like this:

           $ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust

       This tracepoint provider shared object isn’t linked with the user
       application: it must be loaded manually. This is why the application
       is built with no mention of this tracepoint provider, but still needs
       libdl:

           $ cc -o app app.o tp-define.o -ldl

       There are two ways to dynamically load the tracepoint provider shared
       object:

       ·   Load it manually from the application using dlopen(3)

       ·   Make the dynamic loader load it with the LD_PRELOAD environment
           variable (see ld.so(8))

       If the application does not dynamically load the tracepoint provider
       shared object using one of the methods above, tracing is disabled for
       this application, and the events are not listed in the output of
       lttng-list(1).

       Note that it is not safe to use dlclose(3) on a tracepoint provider
       shared object that is being actively used for tracing, due to a lack
       of reference counting from LTTng-UST to the shared object.

       For example, statically linking a tracepoint provider to a shared
       object which is to be dynamically loaded by an application (a plugin,
       for example) is not safe: the shared object, which contains the
       tracepoint provider, could be dynamically closed (dlclose(3)) at any
       time by the application.

       To instrument a shared object, either:

       ·   Statically link the tracepoint provider to the application, or

       ·   Build the tracepoint provider as a shared object (following the
           procedure shown in this section), and preload it when tracing is
           needed using the LD_PRELOAD environment variable.

   Using LTTng-UST with daemons
       Some extra care is needed when using liblttng-ust with daemon
       applications that call fork(2), clone(2), or BSD’s rfork(2) without a
       following exec(3) family system call. The library liblttng-ust-
       fork.so needs to be preloaded before starting the application with
       the LD_PRELOAD environment variable (see ld.so(8)).

       To use liblttng-ust with a daemon application which closes file
       descriptors that were not opened by it, preload the liblttng-ust-
       fd.so library before you start the application. Typical use cases
       include daemons closing all file descriptors after fork(2), and buggy
       applications doing “double-closes”.

   Context information
       Context information can be prepended by the LTTng-UST tracer before
       each event, or before specific events.

       Context fields can be added to specific channels using
       lttng-add-context(1).

       The following context fields are supported by LTTng-UST:

       cpu_id
           CPU ID.

               Note
               This context field is always enabled, and it cannot be added
               with lttng-add-context(1). Its main purpose is to be used for
               dynamic event filtering. See lttng-enable-event(1) for more
               information about event filtering.

       ip
           Instruction pointer: enables recording the exact address from
           which an event was emitted. This context field can be used to
           reverse-lookup the source location that caused the event to be
           emitted.

       perf:thread:COUNTER
           perf counter named COUNTER. Use lttng add-context --list to list
           the available perf counters.

           Only available on IA-32 and x86-64 architectures.

       perf:thread:raw:rN:NAME
           perf counter with raw ID N and custom name NAME. See
           lttng-add-context(1) for more details.

       pthread_id
           POSIX thread identifier. Can be used on architectures where
           pthread_t maps nicely to an unsigned long type.

       procname
           Thread name, as set by exec(3) or prctl(2). It is recommended
           that programs set their thread name with prctl(2) before hitting
           the first tracepoint for that thread.

       vpid
           Virtual process ID: process ID as seen from the point of view of
           the process namespace.

       vtid
           Virtual thread ID: thread ID as seen from the point of view of
           the process namespace.

   LTTng-UST state dump
       If an application that uses liblttng-ust becomes part of a tracing
       session, information about its currently loaded shared objects, their
       build IDs, and their debug link information are emitted as events by
       the tracer.

       The following LTTng-UST state dump events exist and must be enabled
       to record application state dumps. Note that, during the state dump
       phase, LTTng-UST can also emit shared library load/unload events (see
       Shared library load/unload tracking below).

       lttng_ust_statedump:start
           Emitted when the state dump begins.

           This event has no fields.

       lttng_ust_statedump:end
           Emitted when the state dump ends. Once this event is emitted, it
           is guaranteed that, for a given process, the state dump is
           complete.

           This event has no fields.

       lttng_ust_statedump:bin_info
           Emitted when information about a currently loaded executable or
           shared object is found.

           Fields:

           ┌───────────────┬────────────────────────────────┐
           │Field name     Description                    │
           ├───────────────┼────────────────────────────────┤
           │baddr          │ Base address of loaded         │
           │               │ executable.                    │
           ├───────────────┼────────────────────────────────┤
           │memsz          │ Size of loaded executable      │
           │               │ in memory.                     │
           ├───────────────┼────────────────────────────────┤
           │path           │ Path to loaded executable      │
           │               │ file.                          │
           ├───────────────┼────────────────────────────────┤
           │is_pic         │ Whether or not the             │
           │               │ executable is                  │
           │               │ position-independent           │
           │               │ code.                          │
           ├───────────────┼────────────────────────────────┤
           │has_build_id   │ Whether or not the             │
           │               │ executable has a build         │
           │               │ ID. If this field is 1,        │
           │               │ you can expect that an         │
           │               │ lttng_ust_statedump:build_id   │
           │               │ event record follows this      │
           │               │ one (not necessarily           │
           │               │ immediately after).            │
           ├───────────────┼────────────────────────────────┤
           │has_debug_link │ Whether or not the             │
           │               │ executable has debug link      │
           │               │ information. If this field     │
           │               │ is 1, you can expect that an   │
           │               │ lttng_ust_statedump:debug_link │
           │               │ event record follows this      │
           │               │ one (not necessarily           │
           │               │ immediately after).            │
           └───────────────┴────────────────────────────────┘

       lttng_ust_statedump:build_id
           Emitted when a build ID is found in a currently loaded shared
           library. See Debugging Information in Separate Files
           <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
           Files.html> for more information about build IDs.

           Fields:

           ┌───────────┬────────────────────────┐
           │Field name Description            │
           ├───────────┼────────────────────────┤
           │baddr      │ Base address of loaded │
           │           │ library.               │
           ├───────────┼────────────────────────┤
           │build_id   │ Build ID.              │
           └───────────┴────────────────────────┘

       lttng_ust_statedump:debug_link
           Emitted when debug link information is found in a currently
           loaded shared library. See Debugging Information in Separate
           Files <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
           Files.html> for more information about debug links.

           Fields:

           ┌───────────┬────────────────────────┐
           │Field name Description            │
           ├───────────┼────────────────────────┤
           │baddr      │ Base address of loaded │
           │           │ library.               │
           ├───────────┼────────────────────────┤
           │crc        │ Debug link file’s CRC. │
           ├───────────┼────────────────────────┤
           │filename   │ Debug link file name.  │
           └───────────┴────────────────────────┘

   Shared library load/unload tracking
       The LTTng-UST state dump and the LTTng-UST helper library to
       instrument the dynamic linker (see liblttng-ust-dl(3)) can emit
       shared library load/unload tracking events.

       The following shared library load/unload tracking events exist and
       must be enabled to track the loading and unloading of shared
       libraries:

       lttng_ust_lib:load
           Emitted when a shared library (shared object) is loaded.

           Fields:

           ┌───────────────┬───────────────────────────┐
           │Field name     Description               │
           ├───────────────┼───────────────────────────┤
           │baddr          │ Base address of loaded    │
           │               │ library.                  │
           ├───────────────┼───────────────────────────┤
           │memsz          │ Size of loaded library in │
           │               │ memory.                   │
           ├───────────────┼───────────────────────────┤
           │path           │ Path to loaded library    │
           │               │ file.                     │
           ├───────────────┼───────────────────────────┤
           │has_build_id   │ Whether or not the        │
           │               │ library has a build ID.   │
           │               │ If this field is 1, you   │
           │               │ can expect that an        │
           │               │ lttng_ust_lib:build_id    │
           │               │ event record follows this │
           │               │ one (not necessarily      │
           │               │ immediately after).       │
           ├───────────────┼───────────────────────────┤
           │has_debug_link │ Whether or not the        │
           │               │ library has debug link    │
           │               │ information. If this      │
           │               │ field is 1, you can       │
           │               │ expect that an            │
           │               │ lttng_ust_lib:debug_link  │
           │               │ event record follows this │
           │               │ one (not necessarily      │
           │               │ immediately after).       │
           └───────────────┴───────────────────────────┘

       lttng_ust_lib:unload
           Emitted when a shared library (shared object) is unloaded.

           Fields:

           ┌───────────┬──────────────────────────┐
           │Field name Description              │
           ├───────────┼──────────────────────────┤
           │baddr      │ Base address of unloaded │
           │           │ library.                 │
           └───────────┴──────────────────────────┘

       lttng_ust_lib:build_id
           Emitted when a build ID is found in a loaded shared library
           (shared object). See Debugging Information in Separate Files
           <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
           Files.html> for more information about build IDs.

           Fields:

           ┌───────────┬────────────────────────┐
           │Field name Description            │
           ├───────────┼────────────────────────┤
           │baddr      │ Base address of loaded │
           │           │ library.               │
           ├───────────┼────────────────────────┤
           │build_id   │ Build ID.              │
           └───────────┴────────────────────────┘

       lttng_ust_lib:debug_link
           Emitted when debug link information is found in a loaded shared
           library (shared object). See Debugging Information in Separate
           Files <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
           Files.html> for more information about debug links.

           Fields:

           ┌───────────┬────────────────────────┐
           │Field name Description            │
           ├───────────┼────────────────────────┤
           │baddr      │ Base address of loaded │
           │           │ library.               │
           ├───────────┼────────────────────────┤
           │crc        │ Debug link file’s CRC. │
           ├───────────┼────────────────────────┤
           │filename   │ Debug link file name.  │
           └───────────┴────────────────────────┘

   Detect if LTTng-UST is loaded
       To detect if liblttng-ust is loaded from an application:

        1. Define the lttng_ust_loaded weak symbol globally:

               int lttng_ust_loaded __attribute__((weak));

           This weak symbol is set by the constructor of liblttng-ust.

        2. Test lttng_ust_loaded where needed:

               /* ... */

               if (lttng_ust_loaded) {
                   /* LTTng-UST is loaded */
               } else {
                   /* LTTng-UST is NOT loaded */
               }

               /* ... */

EXAMPLE         top

           Note
           A few examples are available in the doc/examples
           <https://github.com/lttng/lttng-ust/tree/master/doc/examples>
           directory of LTTng-UST’s source tree.

       This example shows all the features documented in the previous
       sections. The static linking method is chosen here to link the
       application with the tracepoint provider.

       You can compile the source files and link them together statically
       like this:

           $ cc -c -I. tp.c
           $ cc -c app.c
           $ cc -o app tp.o app.o -llttng-ust -ldl

       Using the lttng(1) tool, create an LTTng tracing session, enable all
       the events of this tracepoint provider, and start tracing:

           $ lttng create my-session
           $ lttng enable-event --userspace 'my_provider:*'
           $ lttng start

       You may also enable specific events:

           $ lttng enable-event --userspace my_provider:big_event
           $ lttng enable-event --userspace my_provider:event_instance2

       Run the application:

           $ ./app some arguments

       Stop the current tracing session and inspect the recorded events:

           $ lttng stop
           $ lttng view

   Tracepoint provider header file
       tp.h:

           #undef TRACEPOINT_PROVIDER
           #define TRACEPOINT_PROVIDER my_provider

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

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

           #include <lttng/tracepoint.h>
           #include <stdio.h>

           #include "app.h"

           TRACEPOINT_EVENT(
               my_provider,
               simple_event,
               TP_ARGS(
                   int, my_integer_arg,
                   const char *, my_string_arg
               ),
               TP_FIELDS(
                   ctf_string(argc, my_string_arg)
                   ctf_integer(int, argv, my_integer_arg)
               )
           )

           TRACEPOINT_ENUM(
               my_provider,
               my_enum,
               TP_ENUM_VALUES(
                   ctf_enum_value("ZERO", 0)
                   ctf_enum_value("ONE", 1)
                   ctf_enum_value("TWO", 2)
                   ctf_enum_range("A RANGE", 52, 125)
                   ctf_enum_value("ONE THOUSAND", 1000)
               )
           )

           TRACEPOINT_EVENT(
               my_provider,
               big_event,
               TP_ARGS(
                   int, my_integer_arg,
                   const char *, my_string_arg,
                   FILE *, stream,
                   double, flt_arg,
                   int *, array_arg
               ),
               TP_FIELDS(
                   ctf_integer(int, int_field1, my_integer_arg * 2)
                   ctf_integer_hex(long int, stream_pos, ftell(stream))
                   ctf_float(double, float_field, flt_arg)
                   ctf_string(string_field, my_string_arg)
                   ctf_array(int, array_field, array_arg, 7)
                   ctf_array_text(char, array_text_field, array_arg, 5)
                   ctf_sequence(int, seq_field, array_arg, int,
                                my_integer_arg / 10)
                   ctf_sequence_text(char, seq_text_field, array_arg,
                                     int, my_integer_arg / 5)
                   ctf_enum(my_provider, my_enum, int,
                            enum_field, array_arg[1])
               )
           )

           TRACEPOINT_LOGLEVEL(my_provider, big_event, TRACE_WARNING)

           TRACEPOINT_EVENT_CLASS(
               my_provider,
               my_tracepoint_class,
               TP_ARGS(
                   int, my_integer_arg,
                   struct app_struct *, app_struct_arg
               ),
               TP_FIELDS(
                   ctf_integer(int, a, my_integer_arg)
                   ctf_integer(unsigned long, b, app_struct_arg->b)
                   ctf_string(c, app_struct_arg->c)
               )
           )

           TRACEPOINT_EVENT_INSTANCE(
               my_provider,
               my_tracepoint_class,
               event_instance1,
               TP_ARGS(
                   int, my_integer_arg,
                   struct app_struct *, app_struct_arg
               )
           )

           TRACEPOINT_EVENT_INSTANCE(
               my_provider,
               my_tracepoint_class,
               event_instance2,
               TP_ARGS(
                   int, my_integer_arg,
                   struct app_struct *, app_struct_arg
               )
           )

           TRACEPOINT_LOGLEVEL(my_provider, event_instance2, TRACE_INFO)

           TRACEPOINT_EVENT_INSTANCE(
               my_provider,
               my_tracepoint_class,
               event_instance3,
               TP_ARGS(
                   int, my_integer_arg,
                   struct app_struct *, app_struct_arg
               )
           )

           #endif /* _TP_H */

           #include <lttng/tracepoint-event.h>

   Tracepoint provider source file
       tp.c:

           #define TRACEPOINT_CREATE_PROBES
           #define TRACEPOINT_DEFINE

           #include "tp.h"

   Application header file
       app.h:

           #ifndef _APP_H
           #define _APP_H

           struct app_struct {
               unsigned long b;
               const char *c;
               double d;
           };

           #endif /* _APP_H */

   Application source file
       app.c:

           #include <stdlib.h>
           #include <stdio.h>

           #include "tp.h"
           #include "app.h"

           static int array_of_ints[] = {
               100, -35, 1, 23, 14, -6, 28, 1001, -3000,
           };

           int main(int argc, char* argv[])
           {
               FILE *stream;
               struct app_struct app_struct;

               tracepoint(my_provider, simple_event, argc, argv[0]);
               stream = fopen("/tmp/app.txt", "w");

               if (!stream) {
                   fprintf(stderr,
                           "Error: Cannot open /tmp/app.txt for writing\n");
                   return EXIT_FAILURE;
               }

               if (fprintf(stream, "0123456789") != 10) {
                   fclose(stream);
                   fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n");
                   return EXIT_FAILURE;
               }

               tracepoint(my_provider, big_event, 35, "hello tracepoint",
                          stream, -3.14, array_of_ints);
               fclose(stream);
               app_struct.b = argc;
               app_struct.c = "[the string]";
               tracepoint(my_provider, event_instance1, 23, &app_struct);
               app_struct.b = argc * 5;
               app_struct.c = "[other string]";
               tracepoint(my_provider, event_instance2, 17, &app_struct);
               app_struct.b = 23;
               app_struct.c = "nothing";
               tracepoint(my_provider, event_instance3, -52, &app_struct);

               return EXIT_SUCCESS;
           }

ENVIRONMENT VARIABLES         top

       LTTNG_HOME
           Alternative user’s home directory. This variable is useful when
           the user running the instrumented application has a non-writable
           home directory.

           Unix sockets used for the communication between liblttng-ust and
           the LTTng session and consumer daemons (part of the LTTng-tools
           project) are located in a specific directory under $LTTNG_HOME
           (or $HOME if $LTTNG_HOME is not set).

       LTTNG_UST_BLOCKING_RETRY_TIMEOUT
           Maximum duration (milliseconds) to retry event tracing when
           there’s no space left for the event record in the sub-buffer.

           0 (default)
               Never block the application.

           Positive value
               Block the application for the specified number of
               milliseconds. If there’s no space left after this duration,
               discard the event record.

           Negative value
               Block the application until there’s space left for the event
               record.

           This option can be useful in workloads generating very large
           trace data throughput, where blocking the application is an
           acceptable trade-off to prevent discarding event records.

               Warning
               Setting this environment variable to a non-zero value may
               significantly affect application timings.

       LTTNG_UST_CLOCK_PLUGIN
           Path to the shared object which acts as the clock override
           plugin. An example of such a plugin can be found in the LTTng-UST
           documentation under examples/clock-override
           <https://github.com/lttng/lttng-
           ust/tree/master/doc/examples/clock-override>.

       LTTNG_UST_DEBUG
           Activates liblttng-ust's debug and error output if set to 1.

       LTTNG_UST_GETCPU_PLUGIN
           Path to the shared object which acts as the getcpu() override
           plugin. An example of such a plugin can be found in the LTTng-UST
           documentation under examples/getcpu-override
           <https://github.com/lttng/lttng-
           ust/tree/master/doc/examples/getcpu-override>.

       LTTNG_UST_REGISTER_TIMEOUT
           Waiting time for the registration done session daemon command
           before proceeding to execute the main program (milliseconds).

           The value 0 means do not wait. The value -1 means wait forever.
           Setting this environment variable to 0 is recommended for
           applications with time constraints on the process startup time.

           Default: 3000.

       LTTNG_UST_BLOCKING_RETRY_TIMEOUT
           Maximum time during which event tracing retry is attempted on
           buffer full condition (millliseconds). Setting this environment
           to non-zero value effectively blocks the application on buffer
           full condition. Setting this environment variable to non-zero
           values may significantly affect application timings. Setting this
           to a negative value may block the application indefinitely if
           there is no consumer emptying the ring buffer. The delay between
           retry attempts is the minimum between the specified timeout value
           and 100ms. This option can be useful in workloads generating very
           large trace data throughput, where blocking the application is an
           acceptable trade-off to not discard events.  Use with caution.

           The value 0 means do not retry. The value -1 means retry forever.
           Value > 0 means a maximum timeout of the given value.

           Default: 0.

       LTTNG_UST_WITHOUT_BADDR_STATEDUMP
           Prevents liblttng-ust from performing a base address state dump
           (see the LTTng-UST state dump section above) if set to 1.

BUGS         top

       If you encounter any issue or usability problem, please report it on
       the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>.

RESOURCES         top

       ·   LTTng project website <http://lttng.org>

       ·   LTTng documentation <http://lttng.org/docs>

       ·   Git repositories <http://git.lttng.org>

       ·   GitHub organization <http://github.com/lttng>

       ·   Continuous integration <http://ci.lttng.org/>

       ·   Mailing list <http://lists.lttng.org> for support and
           development: lttng-dev@lists.lttng.org

       ·   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net

COPYRIGHTS         top

       This library is part of the LTTng-UST project.

       This library is distributed under the GNU Lesser General Public
       License, version 2.1 <http://www.gnu.org/licenses/old-
       licenses/lgpl-2.1.en.html>. See the COPYING
       <https://github.com/lttng/lttng-ust/blob/master/COPYING> file for
       more details.

THANKS         top

       Thanks to Ericsson for funding this work, providing real-life use
       cases, and testing.

       Special thanks to Michel Dagenais and the DORSAL laboratory
       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal
       for the LTTng journey.

AUTHORS         top

       LTTng-UST was originally written by Mathieu Desnoyers, with
       additional contributions from various other people. It is currently
       maintained by Mathieu Desnoyers
       <mailto:mathieu.desnoyers@efficios.com>.

SEE ALSO         top

       tracef(3), tracelog(3), lttng-gen-tp(1), lttng-ust-dl(3),
       lttng-ust-cyg-profile(3), lttng(1), lttng-enable-event(1),
       lttng-list(1), lttng-add-context(1), babeltrace(1), dlopen(3),
       ld.so(8)

COLOPHON         top

       This page is part of the LTTng-UST (    LTTng Userspace Tracer)
       project.  Information about the project can be found at 
       ⟨http://lttng.org/⟩.  It is not known how to report bugs for this man
       page; if you know, please send a mail to man-pages@man7.org.  This
       page was obtained from the project's upstream Git repository 
       ⟨git://git.lttng.org/lttng-ust.git⟩ on 2017-05-03.  If you discover
       any rendering problems in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the page, or
       you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a mail
       to man-pages@man7.org

LTTng 2.9.0-rc1                  04/24/2017                     LTTNG-UST(3)

Pages that refer to this page: lttng(1)lttng-crash(1)lttng-gen-tp(1)lttng-health-check(3)lttng-ust-cyg-profile(3)lttng-ust-dl(3)tracef(3)tracelog(3)lttng-relayd(8)lttng-sessiond(8)