FreeBSD Manual Pages
LTTNG_UST_TRACELOG(3) LTTng Manual LTTNG_UST_TRACELOG(3) NAME lttng_ust_tracelog, lttng_ust_vtracelog - LTTng-UST printf(3)-like inter- face with a log level SYNOPSIS #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> (di- rectly or indirectly): -llttng-ust-common DESCRIPTION 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 <lt- tng/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 lt- tng_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 fol- lowing fields: +------------+-----------------------------+ | Field name | Description | +------------+-----------------------------+ | | | | line | Line in source file where | | | lttng_ust_tracelog() was | | | called. | +------------+-----------------------------+ | | | | file | Source file from which lt- | | | tng_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 lt- tng_ust_tracelog()/lttng_ust_vtracelog() call, use lttng_ust_tracef(3) in- stead. See also the LIMITATIONS section below for important limitations to con- sider when using lttng_ust_tracelog() or lttng_ust_vtracelog(). EXAMPLE 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 lt- tng_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 The lttng_ust_tracelog() and lttng_ust_vtracelog() utility macros were de- veloped to make user space tracing super simple, albeit with notable disad- vantages 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 li- brary's vasprintf(3) function in the background to format the strings at run time, their expected performance is lower than using custom tra- cepoint 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 pro- totyping and debugging, but should not be considered for any permanent/se- rious 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 If you encounter any issue or usability problem, please report it on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>. RESOURCES * 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: lt- tng-dev@lists.lttng.org * IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net COPYRIGHTS This macro is part of the LTTng-UST project. This macro is distributed under the GNU Lesser General Public License, ver- sion 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.13/COPYING> file for more details. THANKS 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 Ecole Polytechnique de Montreal for the LTTng journey. AUTHORS LTTng-UST was originally written by Mathieu Desnoyers, with additional con- tributions from various other people. It is currently maintained by Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>. SEE ALSO lttng_ust_tracef(3), lttng_ust_vtracef(3), lttng-ust(3), lttng(1), printf(3) LTTng 2.13.9 08/02/2026 LTTNG_UST_TRACELOG(3)
NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | LIMITATIONS | BUGS | RESOURCES | COPYRIGHTS | THANKS | AUTHORS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=lttng_ust_tracelog&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>