LTTng-UST printf (3) -подобный интерфейс (LTTng-UST printf(3)-like interface)
Имя (Name)
tracef - LTTng-UST printf(3)-like interface
Синопсис (Synopsis)
#include <lttng/tracef.h>
#define tracef(fmt, ...)
Link with -llttng-ust.
Описание (Description)
The LTTng-UST tracef() API allows you to trace your application
with the help of a simple printf(3)-like macro. The fmt argument
is passed directly to the fmt parameter of vasprintf(3), as well
as the optional parameters following fmt.
To use tracef(), include <lttng/tracef.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 tracef() calls and
ready to run, use lttng-enable-event(1) to enable the
lttng_ust_tracef:* event.
The tracef() events contain a single field, named msg, which is
the formatted string output.
If you need to attach a specific log level to a tracef() call,
use tracelog(3) instead.
See also the LIMITATIONS section below for important limitations
to consider when using tracef().
Примеры (Examples)
Here's a usage example of tracef():
#include <stdlib.h>
#include <lttng/tracef.h>
int main(void)
{
int i;
for (i = 0; i < 25; i++) {
tracef("my message: %s, this integer: %d", "a message", i);
}
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 the tracef()
events, and start the created tracing session like this:
$ lttng create my-session
$ lttng enable-event --userspace 'lttng_ust_tracef:*'
$ lttng start
Next, start the program to be traced:
$ ./app
Finally, stop the tracing session, and inspect the recorded
events:
$ lttng stop
$ lttng view
Ограничения (Limitations)
The tracef() 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 tracef() 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, tracef() 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
