Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
TRACEF(3)			 LTTng Manual			     TRACEF(3)

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().

EXAMPLE
       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:

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

       o   There's no static type checking.

       o   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.

       o   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.

       o   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
       o   LTTng project website <http://lttng.org>

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

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

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

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

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

       o   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,
       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
       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
       contributions from various other	people.	It is currently	maintained by
       Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.

SEE ALSO
       tracelog(3), lttng-ust(3), lttng(1), printf(3)

LTTng 2.9.0-			  11/29/2016			     TRACEF(3)

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

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tracef&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help