lttng_ust_tracelog(3) — Linux manual page

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

LTTNG_UST_TRACELOG(3)         LTTng Manual         LTTNG_UST_TRACELOG(3)

NAME         top

       lttng_ust_tracelog, lttng_ust_vtracelog - LTTng-UST
       printf(3)-like interface with a log level

SYNOPSIS         top

       #include <lttng/tracelog.h>

       #define lttng_ust_tracelog(level, fmt, ...)
       #define lttng_ust_vtracelog(level, fmt, ap)

       Link with:

       •   -llttng-ust

       •   If you define _LGPL_SOURCE before including
           <lttng/tracelog.h> (directly or indirectly): -llttng-ust-
           common

DESCRIPTION         top

       The LTTng-UST lttng_ust_tracelog() and lttng_ust_vtracelog() API
       allows you to trace your application with the help of simple
       printf(3)-like and vprintf(3)-like macros, with an additional
       parameter for the desired log level.

       The fmt argument is passed directly as the fmt parameter of
       vasprintf(3), as well as:

       For lttng_ust_tracelog()
           The optional parameters following fmt.

       For lttng_ust_vtracelog()
           The ap parameter as the ap parameter of vasprintf(3) (va_list
           type).

       The purpose of lttng_ust_tracelog() and lttng_ust_vtracelog() is
       to ease the migration from logging to tracing.

       The available values for the level parameter are:

       LTTNG_UST_TRACEPOINT_LOGLEVEL_EMERG
           System is unusable.

       LTTNG_UST_TRACEPOINT_LOGLEVEL_ALERT
           Action must be taken immediately.

       LTTNG_UST_TRACEPOINT_LOGLEVEL_CRIT
           Critical conditions.

       LTTNG_UST_TRACEPOINT_LOGLEVEL_ERR
           Error conditions.

       LTTNG_UST_TRACEPOINT_LOGLEVEL_WARNING
           Warning conditions.

       LTTNG_UST_TRACEPOINT_LOGLEVEL_NOTICE
           Normal, but significant, condition.

       LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO
           Informational message.

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

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

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

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

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

       LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_FUNCTION
           Debug information with function-level scope.

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

       LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG
           Debug-level message.

       To use lttng_ust_tracelog() or lttng_ust_vtracelog(), include
       <lttng/tracelog.h> where you need it, and link your application
       with liblttng-ust and liblttng-ust-common. See the EXAMPLE
       section below for a complete usage example.

       Once your application is instrumented with lttng_ust_tracelog()
       and/or lttng_ust_vtracelog() calls and ready to run, use
       lttng-enable-event(1) to enable the lttng_ust_tracelog:* event.
       You can isolate specific log levels with the --loglevel and
       --loglevel-only options of this command.

       The lttng_ust_tracelog() and lttng_ust_vtracelog() events contain
       the following fields:
       ┌────────────┬──────────────────────────┐
       │ Field name Description              │
       ├────────────┼──────────────────────────┤
       │            │                          │
       │ line       │ Line in source file      │
       │            │ where                    │
       │            │ lttng_ust_tracelog() was │
       │            │ called.                  │
       ├────────────┼──────────────────────────┤
       │            │                          │
       │ file       │ Source file from which   │
       │            │ lttng_ust_tracelog() was │
       │            │ called.                  │
       ├────────────┼──────────────────────────┤
       │            │                          │
       │ func       │ Function name from which │
       │            │ lttng_ust_tracelog() was │
       │            │ called.                  │
       ├────────────┼──────────────────────────┤
       │            │                          │
       │ msg        │ Formatted string output. │
       └────────────┴──────────────────────────┘

       If you do not need to attach a specific log level to a
       lttng_ust_tracelog()/lttng_ust_vtracelog() call, use
       lttng_ust_tracef(3) instead.

       See also the LIMITATIONS section below for important limitations
       to consider when using lttng_ust_tracelog() or
       lttng_ust_vtracelog().

EXAMPLE         top

       Here’s a usage example of lttng_ust_tracelog():

           #include <stdlib.h>
           #include <lttng/tracelog.h>

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

               if (argc < 2) {
                   lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_CRIT,
                                      "Not enough arguments: %d", argc);
                   return EXIT_FAILURE;
               }

               lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO,
                                  "Starting app with %d arguments", argc);

               for (i = 0; i < argc; i++) {
                   lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG,
                                      "Argument %d: %s", i, argv[i]);
               }

               lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO,
                                  "Exiting app");
               return EXIT_SUCCESS;
           }

       This C source file, saved as app.c, can be compiled into a
       program like this:

           $ cc -o app app.c -llttng-ust -llttng-ust-common

       You can create an LTTng tracing session, enable all the
       lttng_ust_tracelog() events, and start the created tracing
       session like this:

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

       Or you can enable lttng_ust_tracelog() events matching a log
       level at least as severe as a given log level:

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

       Next, start the program to be traced:

           $ ./app a few arguments passed to this application

       Finally, stop the tracing session, and inspect the recorded
       events:

           $ lttng stop
           $ lttng view

LIMITATIONS         top

       The lttng_ust_tracelog() and lttng_ust_vtracelog() utility macros
       were developed to make user space tracing super simple, albeit
       with notable disadvantages compared to custom, full-fledged
       tracepoint providers:

       •   All generated events have the same provider/event names.

       •   There’s no static type checking.

       •   The only event field with user data you actually get, named
           msg, is a string potentially containing the values you passed
           to the macro using your own format. This also means that you
           cannot use filtering using a custom expression at run time
           because there are no isolated fields.

       •   Since lttng_ust_tracelog() and lttng_ust_vtracelog() use C
           standard library’s vasprintf(3) function in the background to
           format the strings at run time, their expected performance is
           lower than using custom tracepoint providers with typed
           fields, which do not require a conversion to a string.

       •   Generally, a string containing the textual representation of
           the user data fields is not as compact as binary fields in
           the resulting trace.

       Thus, lttng_ust_tracelog()/lttng_ust_vtracelog() are useful for
       quick prototyping and debugging, but should not be considered for
       any permanent/serious application instrumentation.

       lttng_ust_vtracelog() does not have a STAP_PROBEV() call, because
       STAP_PROBEV() does not support va_list. If you need it, you
       should emit this call yourself.

       See lttng-ust(3) to learn more about custom tracepoint providers.

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: [email protected]

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

COPYRIGHTS         top

       This macro is part of the LTTng-UST project.

       This macro 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/v2.14/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:[email protected]>.

SEE ALSO         top

       lttng_ust_tracef(3), lttng_ust_vtracef(3), lttng-ust(3),
       lttng(1), printf(3)

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 [email protected].
       This page was obtained from the tarball fetched from
       ⟨https://lttng.org/files/lttng-ust/⟩ on 2024-06-14.  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 [email protected]

LTTng 2.14.0-pre               06/07/2024          LTTNG_UST_TRACELOG(3)

Pages that refer to this page: lttng-ust(3)lttng_ust_tracef(3)tracelog(3)