Blame doc/man/tracelog.3

Packit c04fcb
'\" t
Packit c04fcb
.\"     Title: tracelog
Packit c04fcb
.\"    Author: [see the "AUTHORS" section]
Packit c04fcb
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
Packit c04fcb
.\"      Date: 06/05/2016
Packit c04fcb
.\"    Manual: LTTng Manual
Packit c04fcb
.\"    Source: LTTng 2.9.0-pre
Packit c04fcb
.\"  Language: English
Packit c04fcb
.\"
Packit c04fcb
.TH "TRACELOG" "3" "06/05/2016" "LTTng 2\&.9\&.0\-pre" "LTTng Manual"
Packit c04fcb
.\" -----------------------------------------------------------------
Packit c04fcb
.\" * Define some portability stuff
Packit c04fcb
.\" -----------------------------------------------------------------
Packit c04fcb
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Packit c04fcb
.\" http://bugs.debian.org/507673
Packit c04fcb
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
Packit c04fcb
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Packit c04fcb
.ie \n(.g .ds Aq \(aq
Packit c04fcb
.el       .ds Aq '
Packit c04fcb
.\" -----------------------------------------------------------------
Packit c04fcb
.\" * set default formatting
Packit c04fcb
.\" -----------------------------------------------------------------
Packit c04fcb
.\" disable hyphenation
Packit c04fcb
.nh
Packit c04fcb
.\" disable justification (adjust text to left margin only)
Packit c04fcb
.ad l
Packit c04fcb
.\" -----------------------------------------------------------------
Packit c04fcb
.\" * MAIN CONTENT STARTS HERE *
Packit c04fcb
.\" -----------------------------------------------------------------
Packit c04fcb
.SH "NAME"
Packit c04fcb
tracelog \- LTTng\-UST printf(3)\-like interface with a log level
Packit c04fcb
.SH "SYNOPSIS"
Packit c04fcb
.sp
Packit c04fcb
.nf
Packit c04fcb
\fB#include <lttng/tracelog\&.h>\fR
Packit c04fcb
.fi
Packit c04fcb
.sp
Packit c04fcb
.nf
Packit c04fcb
#define \fBtracelog\fR(\fIlevel\fR, \fIfmt\fR, \&...)
Packit c04fcb
.fi
Packit c04fcb
.sp
Packit c04fcb
Link with \fB-llttng-ust\fR\&.
Packit c04fcb
.SH "DESCRIPTION"
Packit c04fcb
.sp
Packit c04fcb
The LTTng\-UST \fBtracelog()\fR API allows you to trace your application with the help of a simple \fBprintf\fR(3)\-like macro, with an additional parameter for the desired log level\&. The \fIfmt\fR argument is passed directly to the \fIfmt\fR parameter of \fBvasprintf\fR(3), as well as the optional parameters following \fIfmt\fR\&.
Packit c04fcb
.sp
Packit c04fcb
The purpose of \fBtracelog()\fR is to ease the migration from logging to tracing\&.
Packit c04fcb
.sp
Packit c04fcb
The available values for the \fIlevel\fR parameter are:
Packit c04fcb
.PP
Packit c04fcb
\fBTRACE_EMERG\fR
Packit c04fcb
.RS 4
Packit c04fcb
System is unusable\&.
Packit c04fcb
.RE
Packit c04fcb
.PP
Packit c04fcb
\fBTRACE_ALERT\fR
Packit c04fcb
.RS 4
Packit c04fcb
Action must be taken immediately\&.
Packit c04fcb
.RE
Packit c04fcb
.PP
Packit c04fcb
\fBTRACE_CRIT\fR
Packit c04fcb
.RS 4
Packit c04fcb
Critical conditions\&.
Packit c04fcb
.RE
Packit c04fcb
.PP
Packit c04fcb
\fBTRACE_ERR\fR
Packit c04fcb
.RS 4
Packit c04fcb
Error conditions\&.
Packit c04fcb
.RE
Packit c04fcb
.PP
Packit c04fcb
\fBTRACE_WARNING\fR
Packit c04fcb
.RS 4
Packit c04fcb
Warning conditions\&.
Packit c04fcb
.RE
Packit c04fcb
.PP
Packit c04fcb
\fBTRACE_NOTICE\fR
Packit c04fcb
.RS 4
Packit c04fcb
Normal, but significant, condition\&.
Packit c04fcb
.RE
Packit c04fcb
.PP
Packit c04fcb
\fBTRACE_INFO\fR
Packit c04fcb
.RS 4
Packit c04fcb
Informational message\&.
Packit c04fcb
.RE
Packit c04fcb
.PP
Packit c04fcb
\fBTRACE_DEBUG_SYSTEM\fR
Packit c04fcb
.RS 4
Packit c04fcb
Debug information with system\-level scope (set of programs)\&.
Packit c04fcb
.RE
Packit c04fcb
.PP
Packit c04fcb
\fBTRACE_DEBUG_PROGRAM\fR
Packit c04fcb
.RS 4
Packit c04fcb
Debug information with program\-level scope (set of processes)\&.
Packit c04fcb
.RE
Packit c04fcb
.PP
Packit c04fcb
\fBTRACE_DEBUG_PROCESS\fR
Packit c04fcb
.RS 4
Packit c04fcb
Debug information with process\-level scope (set of modules)\&.
Packit c04fcb
.RE
Packit c04fcb
.PP
Packit c04fcb
\fBTRACE_DEBUG_MODULE\fR
Packit c04fcb
.RS 4
Packit c04fcb
Debug information with module (executable/library) scope (set of units)\&.
Packit c04fcb
.RE
Packit c04fcb
.PP
Packit c04fcb
\fBTRACE_DEBUG_UNIT\fR
Packit c04fcb
.RS 4
Packit c04fcb
Debug information with compilation unit scope (set of functions)\&.
Packit c04fcb
.RE
Packit c04fcb
.PP
Packit c04fcb
\fBTRACE_DEBUG_FUNCTION\fR
Packit c04fcb
.RS 4
Packit c04fcb
Debug information with function\-level scope\&.
Packit c04fcb
.RE
Packit c04fcb
.PP
Packit c04fcb
\fBTRACE_DEBUG_LINE\fR
Packit c04fcb
.RS 4
Packit c04fcb
Debug information with line\-level scope (default log level)\&.
Packit c04fcb
.RE
Packit c04fcb
.PP
Packit c04fcb
\fBTRACE_DEBUG\fR
Packit c04fcb
.RS 4
Packit c04fcb
Debug\-level message\&.
Packit c04fcb
.RE
Packit c04fcb
.sp
Packit c04fcb
To use \fBtracelog()\fR, include \fB<lttng/tracelog.h>\fR where you need it, and link your application with \fBliblttng-ust\fR\&. See the \fIEXAMPLE\fR section below for a complete usage example\&.
Packit c04fcb
.sp
Packit c04fcb
Once your application is instrumented with \fBtracelog()\fR calls and ready to run, use \fBlttng-enable-event\fR(1) to enable the \fBlttng_ust_tracelog:*\fR event\&. You can isolate specific log levels with the \fB--loglevel\fR and \fB--loglevel-only\fR options of this command\&.
Packit c04fcb
.sp
Packit c04fcb
The \fBtracelog()\fR events contain the following fields:
Packit c04fcb
.TS
Packit c04fcb
allbox tab(:);
Packit c04fcb
ltB ltB.
Packit c04fcb
T{
Packit c04fcb
Field name
Packit c04fcb
T}:T{
Packit c04fcb
Description
Packit c04fcb
T}
Packit c04fcb
.T&
Packit c04fcb
lt lt
Packit c04fcb
lt lt
Packit c04fcb
lt lt
Packit c04fcb
lt lt.
Packit c04fcb
T{
Packit c04fcb
.sp
Packit c04fcb
\fBline\fR
Packit c04fcb
T}:T{
Packit c04fcb
.sp
Packit c04fcb
Line in source file where \fBtracelog()\fR was called
Packit c04fcb
T}
Packit c04fcb
T{
Packit c04fcb
.sp
Packit c04fcb
\fBfile\fR
Packit c04fcb
T}:T{
Packit c04fcb
.sp
Packit c04fcb
Source file from which \fBtracelog()\fR was called
Packit c04fcb
T}
Packit c04fcb
T{
Packit c04fcb
.sp
Packit c04fcb
\fBfunc\fR
Packit c04fcb
T}:T{
Packit c04fcb
.sp
Packit c04fcb
Function name from which \fBtracelog()\fR was called
Packit c04fcb
T}
Packit c04fcb
T{
Packit c04fcb
.sp
Packit c04fcb
\fBmsg\fR
Packit c04fcb
T}:T{
Packit c04fcb
.sp
Packit c04fcb
Formatted string output
Packit c04fcb
T}
Packit c04fcb
.TE
Packit c04fcb
.sp 1
Packit c04fcb
.sp
Packit c04fcb
If you do not need to attach a specific log level to a \fBtracelog()\fR call, use \fBtracef\fR(3) instead\&.
Packit c04fcb
.sp
Packit c04fcb
See also the \fILIMITATIONS\fR section below for important limitations to consider when using \fBtracelog()\fR\&.
Packit c04fcb
.SH "EXAMPLE"
Packit c04fcb
.sp
Packit c04fcb
Here\(cqs a usage example of \fBtracelog()\fR:
Packit c04fcb
.sp
Packit c04fcb
.if n \{\
Packit c04fcb
.RS 4
Packit c04fcb
.\}
Packit c04fcb
.nf
Packit c04fcb
#include <stdlib\&.h>
Packit c04fcb
#include <lttng/tracelog\&.h>
Packit c04fcb
Packit c04fcb
int main(int argc, char *argv[])
Packit c04fcb
{
Packit c04fcb
    int i;
Packit c04fcb
Packit c04fcb
    if (argc < 2) {
Packit c04fcb
        tracelog(TRACE_CRIT, "Not enough arguments: %d", argc);
Packit c04fcb
        return EXIT_FAILURE;
Packit c04fcb
    }
Packit c04fcb
Packit c04fcb
    tracelog(TRACE_INFO, "Starting app with %d arguments", argc);
Packit c04fcb
Packit c04fcb
    for (i = 0; i < argc; i++) {
Packit c04fcb
        tracelog(TRACE_DEBUG, "Argument %d: %s", i, argv[i]);
Packit c04fcb
    }
Packit c04fcb
Packit c04fcb
    tracelog(TRACE_INFO, "Exiting app");
Packit c04fcb
Packit c04fcb
    return EXIT_SUCCESS;
Packit c04fcb
}
Packit c04fcb
.fi
Packit c04fcb
.if n \{\
Packit c04fcb
.RE
Packit c04fcb
.\}
Packit c04fcb
.sp
Packit c04fcb
This C source file, saved as \fBapp.c\fR, can be compiled into a program like this:
Packit c04fcb
.sp
Packit c04fcb
.if n \{\
Packit c04fcb
.RS 4
Packit c04fcb
.\}
Packit c04fcb
.nf
Packit c04fcb
cc \-o app app\&.c \-llttng\-ust
Packit c04fcb
.fi
Packit c04fcb
.if n \{\
Packit c04fcb
.RE
Packit c04fcb
.\}
Packit c04fcb
.sp
Packit c04fcb
You can create an LTTng tracing session, enable all the \fBtracelog()\fR events, and start the created tracing session like this:
Packit c04fcb
.sp
Packit c04fcb
.if n \{\
Packit c04fcb
.RS 4
Packit c04fcb
.\}
Packit c04fcb
.nf
Packit c04fcb
lttng create my\-session
Packit c04fcb
lttng enable\-event \-\-userspace \*(Aqlttng_ust_tracelog:*\*(Aq
Packit c04fcb
lttng start
Packit c04fcb
.fi
Packit c04fcb
.if n \{\
Packit c04fcb
.RE
Packit c04fcb
.\}
Packit c04fcb
.sp
Packit c04fcb
Or you can enable \fBtracelog()\fR events matching a log level at least as severe as a given log level:
Packit c04fcb
.sp
Packit c04fcb
.if n \{\
Packit c04fcb
.RS 4
Packit c04fcb
.\}
Packit c04fcb
.nf
Packit c04fcb
lttng enable\-event \-\-userspace \*(Aqlttng_ust_tracelog:*\*(Aq \e
Packit c04fcb
                   \-\-loglevel=TRACE_INFO
Packit c04fcb
.fi
Packit c04fcb
.if n \{\
Packit c04fcb
.RE
Packit c04fcb
.\}
Packit c04fcb
.sp
Packit c04fcb
Next, start the program to be traced:
Packit c04fcb
.sp
Packit c04fcb
.if n \{\
Packit c04fcb
.RS 4
Packit c04fcb
.\}
Packit c04fcb
.nf
Packit c04fcb
\&./app a few arguments passed to this application
Packit c04fcb
.fi
Packit c04fcb
.if n \{\
Packit c04fcb
.RE
Packit c04fcb
.\}
Packit c04fcb
.sp
Packit c04fcb
Finally, stop the tracing session, and inspect the recorded events:
Packit c04fcb
.sp
Packit c04fcb
.if n \{\
Packit c04fcb
.RS 4
Packit c04fcb
.\}
Packit c04fcb
.nf
Packit c04fcb
lttng stop
Packit c04fcb
lttng view
Packit c04fcb
.fi
Packit c04fcb
.if n \{\
Packit c04fcb
.RE
Packit c04fcb
.\}
Packit c04fcb
.SH "LIMITATIONS"
Packit c04fcb
.sp
Packit c04fcb
The \fBtracelog()\fR utility macro was developed to make user space tracing super simple, albeit with notable disadvantages compared to custom, full\-fledged tracepoint providers:
Packit c04fcb
.sp
Packit c04fcb
.RS 4
Packit c04fcb
.ie n \{\
Packit c04fcb
\h'-04'\(bu\h'+03'\c
Packit c04fcb
.\}
Packit c04fcb
.el \{\
Packit c04fcb
.sp -1
Packit c04fcb
.IP \(bu 2.3
Packit c04fcb
.\}
Packit c04fcb
All generated events have the same provider/event names\&.
Packit c04fcb
.RE
Packit c04fcb
.sp
Packit c04fcb
.RS 4
Packit c04fcb
.ie n \{\
Packit c04fcb
\h'-04'\(bu\h'+03'\c
Packit c04fcb
.\}
Packit c04fcb
.el \{\
Packit c04fcb
.sp -1
Packit c04fcb
.IP \(bu 2.3
Packit c04fcb
.\}
Packit c04fcb
There\(cqs no static type checking\&.
Packit c04fcb
.RE
Packit c04fcb
.sp
Packit c04fcb
.RS 4
Packit c04fcb
.ie n \{\
Packit c04fcb
\h'-04'\(bu\h'+03'\c
Packit c04fcb
.\}
Packit c04fcb
.el \{\
Packit c04fcb
.sp -1
Packit c04fcb
.IP \(bu 2.3
Packit c04fcb
.\}
Packit c04fcb
The only event field with user data you actually get, named
Packit c04fcb
\fBmsg\fR, 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\&.
Packit c04fcb
.RE
Packit c04fcb
.sp
Packit c04fcb
.RS 4
Packit c04fcb
.ie n \{\
Packit c04fcb
\h'-04'\(bu\h'+03'\c
Packit c04fcb
.\}
Packit c04fcb
.el \{\
Packit c04fcb
.sp -1
Packit c04fcb
.IP \(bu 2.3
Packit c04fcb
.\}
Packit c04fcb
Since
Packit c04fcb
\fBtracelog()\fR
Packit c04fcb
uses C standard library\(cqs
Packit c04fcb
\fBvasprintf\fR(3)
Packit c04fcb
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\&.
Packit c04fcb
.RE
Packit c04fcb
.sp
Packit c04fcb
.RS 4
Packit c04fcb
.ie n \{\
Packit c04fcb
\h'-04'\(bu\h'+03'\c
Packit c04fcb
.\}
Packit c04fcb
.el \{\
Packit c04fcb
.sp -1
Packit c04fcb
.IP \(bu 2.3
Packit c04fcb
.\}
Packit c04fcb
Generally, a string containing the textual representation of the user data fields is not as compact as binary fields in the resulting trace\&.
Packit c04fcb
.RE
Packit c04fcb
.sp
Packit c04fcb
Thus, \fBtracelog()\fR is useful for quick prototyping and debugging, but should not be considered for any permanent/serious application instrumentation\&.
Packit c04fcb
.sp
Packit c04fcb
See \fBlttng-ust\fR(3) to learn more about custom tracepoint providers\&.
Packit c04fcb
.SH "BUGS"
Packit c04fcb
.sp
Packit c04fcb
If you encounter any issue or usability problem, please report it on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>\&.
Packit c04fcb
.SH "RESOURCES"
Packit c04fcb
.sp
Packit c04fcb
.RS 4
Packit c04fcb
.ie n \{\
Packit c04fcb
\h'-04'\(bu\h'+03'\c
Packit c04fcb
.\}
Packit c04fcb
.el \{\
Packit c04fcb
.sp -1
Packit c04fcb
.IP \(bu 2.3
Packit c04fcb
.\}
Packit c04fcb
LTTng project website <http://lttng.org>
Packit c04fcb
.RE
Packit c04fcb
.sp
Packit c04fcb
.RS 4
Packit c04fcb
.ie n \{\
Packit c04fcb
\h'-04'\(bu\h'+03'\c
Packit c04fcb
.\}
Packit c04fcb
.el \{\
Packit c04fcb
.sp -1
Packit c04fcb
.IP \(bu 2.3
Packit c04fcb
.\}
Packit c04fcb
LTTng documentation <http://lttng.org/docs>
Packit c04fcb
.RE
Packit c04fcb
.sp
Packit c04fcb
.RS 4
Packit c04fcb
.ie n \{\
Packit c04fcb
\h'-04'\(bu\h'+03'\c
Packit c04fcb
.\}
Packit c04fcb
.el \{\
Packit c04fcb
.sp -1
Packit c04fcb
.IP \(bu 2.3
Packit c04fcb
.\}
Packit c04fcb
Git repositories <http://git.lttng.org>
Packit c04fcb
.RE
Packit c04fcb
.sp
Packit c04fcb
.RS 4
Packit c04fcb
.ie n \{\
Packit c04fcb
\h'-04'\(bu\h'+03'\c
Packit c04fcb
.\}
Packit c04fcb
.el \{\
Packit c04fcb
.sp -1
Packit c04fcb
.IP \(bu 2.3
Packit c04fcb
.\}
Packit c04fcb
GitHub organization <http://github.com/lttng>
Packit c04fcb
.RE
Packit c04fcb
.sp
Packit c04fcb
.RS 4
Packit c04fcb
.ie n \{\
Packit c04fcb
\h'-04'\(bu\h'+03'\c
Packit c04fcb
.\}
Packit c04fcb
.el \{\
Packit c04fcb
.sp -1
Packit c04fcb
.IP \(bu 2.3
Packit c04fcb
.\}
Packit c04fcb
Continuous integration <http://ci.lttng.org/>
Packit c04fcb
.RE
Packit c04fcb
.sp
Packit c04fcb
.RS 4
Packit c04fcb
.ie n \{\
Packit c04fcb
\h'-04'\(bu\h'+03'\c
Packit c04fcb
.\}
Packit c04fcb
.el \{\
Packit c04fcb
.sp -1
Packit c04fcb
.IP \(bu 2.3
Packit c04fcb
.\}
Packit c04fcb
Mailing list <http://lists.lttng.org>
Packit c04fcb
for support and development:
Packit c04fcb
\fBlttng-dev@lists.lttng.org\fR
Packit c04fcb
.RE
Packit c04fcb
.sp
Packit c04fcb
.RS 4
Packit c04fcb
.ie n \{\
Packit c04fcb
\h'-04'\(bu\h'+03'\c
Packit c04fcb
.\}
Packit c04fcb
.el \{\
Packit c04fcb
.sp -1
Packit c04fcb
.IP \(bu 2.3
Packit c04fcb
.\}
Packit c04fcb
IRC channel <irc://irc.oftc.net/lttng>:
Packit c04fcb
\fB#lttng\fR
Packit c04fcb
on
Packit c04fcb
\fBirc.oftc.net\fR
Packit c04fcb
.RE
Packit c04fcb
.SH "COPYRIGHTS"
Packit c04fcb
.sp
Packit c04fcb
This macro is part of the LTTng\-UST project\&.
Packit c04fcb
.sp
Packit c04fcb
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 \fBCOPYING\fR <https://github.com/lttng/lttng-ust/blob/master/COPYING> file for more details\&.
Packit c04fcb
.SH "THANKS"
Packit c04fcb
.sp
Packit c04fcb
Thanks to Ericsson for funding this work, providing real\-life use cases, and testing\&.
Packit c04fcb
.sp
Packit c04fcb
Special thanks to Michel Dagenais and the DORSAL laboratory <http://www.dorsal.polymtl.ca/> at \('Ecole Polytechnique de Montr\('eal for the LTTng journey\&.
Packit c04fcb
.SH "AUTHORS"
Packit c04fcb
.sp
Packit c04fcb
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>\&.
Packit c04fcb
.SH "SEE ALSO"
Packit c04fcb
.sp
Packit c04fcb
\fBtracef\fR(3), \fBlttng-ust\fR(3), \fBlttng\fR(1), \fBprintf\fR(3)