[lttng-ust.git] / doc / man / tracef.3.txt

tracef(3)
=========
:object-type: macro


NAME
----
tracef - LTTng-UST printf(3)-like interface


SYNOPSIS
--------
[verse]
*#include <lttng/tracef.h>*

[verse]
#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 man:printf(3)-like macro. The 'fmt' argument is
passed directly to the 'fmt' parameter of man: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,EXAMPLE>>
section below for a complete usage example.

Once your application is instrumented with `tracef()` calls and
ready to run, use man: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
man:tracelog(3) instead.

See also the <<limitations,LIMITATIONS>> section below for important
limitations to consider when using `tracef()`.


[[example]]
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:

[role="term"]
----
$ 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:

[role="term"]
----
$ lttng create my-session
$ lttng enable-event --userspace 'lttng_ust_tracef:*'
$ lttng start
----

Next, start the program to be traced:

[role="term"]
----
$ ./app
----

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

[role="term"]
----
$ lttng stop
$ lttng view
----


[[limitations]]
LIMITATIONS
-----------
:macro-name: tracef

include::tracef-tracelog-limitations.txt[]


include::common-footer.txt[]

include::common-copyrights.txt[]

include::common-authors.txt[]


SEE ALSO
--------
man:tracelog(3),
man:lttng-ust(3),
man:lttng(1),
man:printf(3)
Commit	Line	Data
4ddbd0b7 PP	1	tracef(3)
	2	=========
	3	:object-type: macro
	4
	5
	6	NAME
	7	----
0810c65b	8	tracef - LTTng-UST printf(3)-like interface
4ddbd0b7 PP	9
	10
	11	SYNOPSIS
	12	--------
	13	[verse]
	14	#include <lttng/tracef.h>
	15
	16	[verse]
	17	#define tracef('fmt', ...)
	18
	19	Link with `-llttng-ust`.
	20
	21
	22	DESCRIPTION
	23	-----------
	24	The LTTng-UST `tracef()` API allows you to trace your application with
	25	the help of a simple man:printf(3)-like macro. The 'fmt' argument is
	26	passed directly to the 'fmt' parameter of man:vasprintf(3), as well as
	27	the optional parameters following 'fmt'.
	28
	29	To use `tracef()`, include `<lttng/tracef.h>` where you need it, and
	30	link your application with `liblttng-ust`. See the <<example,EXAMPLE>>
	31	section below for a complete usage example.
	32
	33	Once your application is instrumented with `tracef()` calls and
	34	ready to run, use man:lttng-enable-event(1) to enable the
	35	`lttng_ust_tracef:*` event.
	36
	37	The `tracef()` events contain a single field, named `msg`, which is the
	38	formatted string output.
	39
	40	If you need to attach a specific log level to a `tracef()` call, use
	41	man:tracelog(3) instead.
	42
	43	See also the <<limitations,LIMITATIONS>> section below for important
	44	limitations to consider when using `tracef()`.
	45
	46
	47	[[example]]
	48	EXAMPLE
	49	-------
	50	Here's a usage example of `tracef()`:
	51
	52	-------------------------------------------------------------------
	53	#include <stdlib.h>
	54	#include <lttng/tracef.h>
	55
	56	int main(void)
	57	{
	58	int i;
	59
	60	for (i = 0; i < 25; i++) {
	61	tracef("my message: %s, this integer: %d", "a message", i);
	62	}
	63
	64	return EXIT_SUCCESS;
	65	}
	66	-------------------------------------------------------------------
	67
	68	This C source file, saved as `app.c`, can be compiled into a program
	69	like this:
	70
	71	[role="term"]
636cf2a0 PP	72	----
	73	$ cc -o app app.c -llttng-ust
	74	----
4ddbd0b7 PP	75
	76	You can create an LTTng tracing session, enable the `tracef()` events,
	77	and start the created tracing session like this:
	78
	79	[role="term"]
636cf2a0 PP	80	----
	81	$ lttng create my-session
	82	$ lttng enable-event --userspace 'lttng_ust_tracef:*'
	83	$ lttng start
	84	----
4ddbd0b7 PP	85
	86	Next, start the program to be traced:
	87
	88	[role="term"]
636cf2a0 PP	89	----
	90	$ ./app
	91	----
4ddbd0b7 PP	92
	93	Finally, stop the tracing session, and inspect the recorded events:
	94
	95	[role="term"]
636cf2a0 PP	96	----
	97	$ lttng stop
	98	$ lttng view
	99	----
4ddbd0b7 PP	100
	101
	102	[[limitations]]
	103	LIMITATIONS
	104	-----------
	105	:macro-name: tracef
	106
	107	include::tracef-tracelog-limitations.txt[]
	108
	109
	110	include::common-footer.txt[]
	111
	112	include::common-copyrights.txt[]
	113
	114	include::common-authors.txt[]
	115
	116
	117	SEE ALSO
	118	--------
	119	man:tracelog(3),
	120	man:lttng-ust(3),
	121	man:lttng(1),
	122	man:printf(3)