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

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


NAME
----
tracelog - LTTng-UST printf(3)-like interface with a log level


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

[verse]
#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 man:printf(3)-like macro, with an additional
parameter for the desired log level. The 'fmt' argument is passed
directly to the 'fmt' parameter of man: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:

include::log-levels.txt[]

To use `tracelog()`, include `<lttng/tracelog.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 `tracelog()` calls and
ready to run, use man:lttng-enable-event(1) to enable the
`lttng_ust_tracelog:*` event. You can isolate specific log levels with
the nloption:--loglevel and nloption:--loglevel-only options of this
command.

The `tracelog()` events contain the following fields:

[options="header"]
|===============================================================
| 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 man:tracef(3) instead.

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


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

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

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

[role="term"]
-------------------------------------------------------
lttng enable-event --userspace 'lttng_ust_tracelog:*' \
                   --loglevel=TRACE_INFO
-------------------------------------------------------

Next, start the program to be traced:

[role="term"]
------------------------------------------------
./app a few arguments passed to this application
------------------------------------------------

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

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


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

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


include::common-footer.txt[]

include::common-copyrights.txt[]

include::common-authors.txt[]


SEE ALSO
--------
man:tracef(3),
man:lttng-ust(3),
man:lttng(1),
man:printf(3)
Commit	Line	Data
4ddbd0b7 PP	1	tracelog(3)
	2	===========
	3	:object-type: macro
	4
	5
	6	NAME
	7	----
0810c65b	8	tracelog - LTTng-UST printf(3)-like interface with a log level
4ddbd0b7 PP	9
	10
	11	SYNOPSIS
	12	--------
	13	[verse]
	14	#include <lttng/tracelog.h>
	15
	16	[verse]
	17	#define tracelog('level', 'fmt', ...)
	18
	19	Link with `-llttng-ust`.
	20
	21
	22	DESCRIPTION
	23	-----------
	24	The LTTng-UST `tracelog()` API allows you to trace your application with
	25	the help of a simple man:printf(3)-like macro, with an additional
	26	parameter for the desired log level. The 'fmt' argument is passed
	27	directly to the 'fmt' parameter of man:vasprintf(3), as well as
	28	the optional parameters following 'fmt'.
	29
	30	The purpose of `tracelog()` is to ease the migration from logging to
	31	tracing.
	32
	33	The available values for the 'level' parameter are:
	34
	35	include::log-levels.txt[]
	36
	37	To use `tracelog()`, include `<lttng/tracelog.h>` where you need it, and
	38	link your application with `liblttng-ust`. See the <<example,EXAMPLE>>
	39	section below for a complete usage example.
	40
	41	Once your application is instrumented with `tracelog()` calls and
	42	ready to run, use man:lttng-enable-event(1) to enable the
	43	`lttng_ust_tracelog:*` event. You can isolate specific log levels with
	44	the nloption:--loglevel and nloption:--loglevel-only options of this
	45	command.
	46
	47	The `tracelog()` events contain the following fields:
	48
	49	[options="header"]
	50	\|===============================================================
	51	\| Field name \| Description
	52	\| `line` \| Line in source file where `tracelog()` was called
	53	\| `file` \| Source file from which `tracelog()` was called
	54	\| `func` \| Function name from which `tracelog()` was called
	55	\| `msg` \| Formatted string output
	56	\|===============================================================
	57
	58	If you do not need to attach a specific log level to a `tracelog()`
	59	call, use man:tracef(3) instead.
	60
	61	See also the <<limitations,LIMITATIONS>> section below for important
	62	limitations to consider when using `tracelog()`.
	63
	64
	65	[[example]]
	66	EXAMPLE
	67	-------
	68	Here's a usage example of `tracelog()`:
	69
	70	-------------------------------------------------------------------
	71	#include <stdlib.h>
	72	#include <lttng/tracelog.h>
73
74	int main(int argc, char *argv[])
75	{
76	int i;
77
78	if (argc < 2) {
79	tracelog(TRACE_CRIT, "Not enough arguments: %d", argc);
80	return EXIT_FAILURE;
81	}
82
83	tracelog(TRACE_INFO, "Starting app with %d arguments", argc);
84
85	for (i = 0; i < argc; i++) {
86	tracelog(TRACE_DEBUG, "Argument %d: %s", i, argv[i]);
87	}
88
89	tracelog(TRACE_INFO, "Exiting app");
90
91	return EXIT_SUCCESS;
92	}
93	-------------------------------------------------------------------
94
95	This C source file, saved as `app.c`, can be compiled into a program
96	like this:
97
98	[role="term"]
99	---------------------------
100	cc -o app app.c -llttng-ust
101	---------------------------
102
103	You can create an LTTng tracing session, enable all the `tracelog()`
104	events, and start the created tracing session like this:
105
106	[role="term"]
107	---------------------------------------------------
108	lttng create my-session
109	lttng enable-event --userspace 'lttng_ust_tracelog:*'
110	lttng start
111	---------------------------------------------------
112
113	Or you can enable `tracelog()` events matching a log level at least
114	as severe as a given log level:
115
116	[role="term"]
117	-------------------------------------------------------
118	lttng enable-event --userspace 'lttng_ust_tracelog:*' \
119	--loglevel=TRACE_INFO
120	-------------------------------------------------------
121
122	Next, start the program to be traced:
123
124	[role="term"]
125	------------------------------------------------
126	./app a few arguments passed to this application
127	------------------------------------------------
128
129	Finally, stop the tracing session, and inspect the recorded events:
130
131	[role="term"]
132	----------
133	lttng stop
134	lttng view
135	----------
136
137
138	[[limitations]]
139	LIMITATIONS
140	-----------
141	:macro-name: tracelog
142
143	include::tracef-tracelog-limitations.txt[]
144
145
146	include::common-footer.txt[]
147
148	include::common-copyrights.txt[]
149
150	include::common-authors.txt[]
151
152
153	SEE ALSO
154	--------
155	man:tracef(3),
156	man:lttng-ust(3),
157	man:lttng(1),
158	man:printf(3)