LTTng-UST printf (3) -подобный интерфейс с лог-уровнем (LTTng-UST printf(3)-like interface with a log level)
Имя (Name)
tracelog - LTTng-UST printf(3)-like interface with a log level
Синопсис (Synopsis)
#include <lttng/tracelog.h>
#define tracelog(level, fmt, ...)
Link with -llttng-ust.
Описание (Description)
The LTTng-UST tracelog() API allows you to trace your application
with the help of a simple printf(3)-like macro, with an
additional parameter for the desired log level. The fmt argument
is passed directly to the fmt parameter of vasprintf(3), as well
as the optional parameters following fmt.
The purpose of tracelog() is to ease the migration from logging
to tracing.
The available values for the level parameter 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.
To use tracelog(), include <lttng/tracelog.h> where you need it,
and link your application with liblttng-ust. See the EXAMPLE
section below for a complete usage example.
Once your application is instrumented with tracelog() 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 tracelog() events contain the following fields:
┌───────────┬──────────────────────────┐
│Field name │ Description │
├───────────┼──────────────────────────┤
│ │ │
│line │ Line in source file │
│ │ where tracelog() was │
│ │ called. │
├───────────┼──────────────────────────┤
│ │ │
│file │ Source file from which │
│ │ tracelog() was called. │
├───────────┼──────────────────────────┤
│ │ │
│func │ Function name from which │
│ │ tracelog() was called. │
├───────────┼──────────────────────────┤
│ │ │
│msg │ Formatted string output. │
└───────────┴──────────────────────────┘
If you do not need to attach a specific log level to a tracelog()
call, use tracef(3) instead.
See also the LIMITATIONS section below for important limitations
to consider when using tracelog().
Примеры (Examples)
Here's a usage example of tracelog():
#include <stdlib.h>
#include <lttng/tracelog.h>
int main(int argc, char *argv[])
{
int i;
if (argc < 2) {
tracelog(TRACE_CRIT, "Not enough arguments: %d", argc);
return EXIT_FAILURE;
}
tracelog(TRACE_INFO, "Starting app with %d arguments", argc);
for (i = 0; i < argc; i++) {
tracelog(TRACE_DEBUG, "Argument %d: %s", i, argv[i]);
}
tracelog(TRACE_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
You can create an LTTng tracing session, enable all the
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 tracelog() events matching a log level at least
as severe as a given log level:
$ lttng enable-event --userspace 'lttng_ust_tracelog:*' \
--loglevel=TRACE_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 tracelog() utility macro was 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 tracelog() uses C standard library's vasprintf(3)
function in the background to format the strings at run time,
its 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, tracelog() is useful for quick prototyping and debugging,
but should not be considered for any permanent/serious
application instrumentation.
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: lttng-dev@lists.lttng.org
• IRC channel <irc://irc.oftc.net/lttng>: #lttng on
irc.oftc.net
