|
Packit |
c04fcb |
'\" t
|
|
Packit |
c04fcb |
.\" Title: lttng-ust-dl
|
|
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 "LTTNG\-UST\-DL" "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 |
lttng-ust-cyg-profile \- Function tracing (LTTng\-UST helper)
|
|
Packit |
c04fcb |
.SH "SYNOPSIS"
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
Compile your application with compiler option \fB-finstrument-functions\fR\&.
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
Launch your application by preloading \fBliblttng-ust-cyg-profile-fast.so\fR for fast function tracing:
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
.nf
|
|
Packit |
c04fcb |
\fBLD_PRELOAD=liblttng\-ust\-cyg\-profile\-fast\&.so\fR my\-app
|
|
Packit |
c04fcb |
.fi
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
Launch your application by preloading \fBliblttng-ust-cyg-profile.so\fR for slower, more verbose function tracing:
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
.nf
|
|
Packit |
c04fcb |
\fBLD_PRELOAD=liblttng\-ust\-cyg\-profile\&.so\fR my\-app
|
|
Packit |
c04fcb |
.fi
|
|
Packit |
c04fcb |
.SH "DESCRIPTION"
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
When the \fBliblttng-ust-cyg-profile.so\fR or the \fBliblttng-ust-cyg-profile-fast.so\fR library is preloaded before a given application starts, all function entry and return points are traced by LTTng\-UST (see \fBlttng-ust\fR(3)), provided said application was compiled with the \fB-finstrument-functions\fR compiler option\&.
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
See \fBlttng\fR(1) to learn more about how to control LTTng tracing sessions\&.
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
Function tracing with LTTng\-UST comes in two flavors, each one providing a different trade\-off between performance and robustness:
|
|
Packit |
c04fcb |
.PP
|
|
Packit |
c04fcb |
\fBliblttng-ust-cyg-profile-fast.so\fR
|
|
Packit |
c04fcb |
.RS 4
|
|
Packit |
c04fcb |
This is a lightweight variant that should only be used where it can be
|
|
Packit |
c04fcb |
\fIguaranteed\fR
|
|
Packit |
c04fcb |
that the complete event stream is recorded without any missing events\&. Any kind of duplicate information is left out\&.
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
At each function entry, the address of the called function is recorded in an LTTng\-UST event\&. Function exits are recorded as another, empty LTTng\-UST event\&.
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
See the
|
|
Packit |
c04fcb |
\fIFast function tracing\fR
|
|
Packit |
c04fcb |
section below for the complete list of emitted events and their fields\&.
|
|
Packit |
c04fcb |
.RE
|
|
Packit |
c04fcb |
.PP
|
|
Packit |
c04fcb |
\fBliblttng-ust-cyg-profile.so\fR
|
|
Packit |
c04fcb |
.RS 4
|
|
Packit |
c04fcb |
This is a more robust variant which also works for use cases where events might get discarded, or not recorded from application startup\&. In these cases, the trace analyzer needs extra information to be able to reconstruct the program flow\&.
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
At each function entry
|
|
Packit |
c04fcb |
\fIand\fR
|
|
Packit |
c04fcb |
exit, the address of the called function
|
|
Packit |
c04fcb |
\fIand\fR
|
|
Packit |
c04fcb |
the call site address are recorded in an LTTng\-UST event\&.
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
See the
|
|
Packit |
c04fcb |
\fIVerbose function tracing\fR
|
|
Packit |
c04fcb |
section below for the complete list of emitted events and their fields\&.
|
|
Packit |
c04fcb |
.RE
|
|
Packit |
c04fcb |
.SS "Usage"
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
To use LTTng\-UST function tracing, you need to make sure the sources of your application are compiled with the \fB-finstrument-functions\fR compiler option\&.
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
It might be necessary to limit the number of source files where this option is used to prevent excessive amount of trace data to be generated at run time\&. Usually, there are additional compiler flags that allow you to specify a more fine\-grained selection of function instrumentation\&.
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
For each instrumented function, the executable will contain calls to profiling function hooks (after function entry, named \fB__cyg_profile_func_enter()\fR, and just before function exit, named \fB__cyg_profile_func_exit()\fR)\&.
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
By preloading (using the \fBLD_PRELOAD\fR environment variable) one of the provided shared libraries, these profiling hooks get defined to emit LTTng events (as described below)\&.
|
|
Packit |
c04fcb |
.if n \{\
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
.\}
|
|
Packit |
c04fcb |
.RS 4
|
|
Packit |
c04fcb |
.it 1 an-trap
|
|
Packit |
c04fcb |
.nr an-no-space-flag 1
|
|
Packit |
c04fcb |
.nr an-break-flag 1
|
|
Packit |
c04fcb |
.br
|
|
Packit |
c04fcb |
.ps +1
|
|
Packit |
c04fcb |
\fBNote\fR
|
|
Packit |
c04fcb |
.ps -1
|
|
Packit |
c04fcb |
.br
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
Using this feature can result in a \fBmassive amount\fR of trace data to be generated by the instrumented application\&. Application run time is also considerably affected\&. Be careful on systems with limited resources\&.
|
|
Packit |
c04fcb |
.sp .5v
|
|
Packit |
c04fcb |
.RE
|
|
Packit |
c04fcb |
.SS "Fast function tracing"
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
The following LTTng\-UST events are available when using \fBliblttng-ust-cyg-profile-fast.so\fR\&. Their log level is set to \fBTRACE_DEBUG_FUNCTION\fR\&.
|
|
Packit |
c04fcb |
.PP
|
|
Packit |
c04fcb |
\fBlttng_ust_cyg_profile_fast:func_entry\fR
|
|
Packit |
c04fcb |
.RS 4
|
|
Packit |
c04fcb |
Emitted when an application function is entered, or more specifically, when
|
|
Packit |
c04fcb |
\fB__cyg_profile_func_enter()\fR
|
|
Packit |
c04fcb |
is called\&.
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
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 |
T{
|
|
Packit |
c04fcb |
\fBfunc_addr\fR
|
|
Packit |
c04fcb |
T}:T{
|
|
Packit |
c04fcb |
Function address
|
|
Packit |
c04fcb |
T}
|
|
Packit |
c04fcb |
.TE
|
|
Packit |
c04fcb |
.sp 1
|
|
Packit |
c04fcb |
.RE
|
|
Packit |
c04fcb |
.PP
|
|
Packit |
c04fcb |
\fBlttng_ust_cyg_profile_fast:func_exit\fR
|
|
Packit |
c04fcb |
.RS 4
|
|
Packit |
c04fcb |
Emitted when an application function returns, or more specifically, when
|
|
Packit |
c04fcb |
\fB__cyg_profile_func_exit()\fR
|
|
Packit |
c04fcb |
is called\&.
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
This event has no fields\&. Since the
|
|
Packit |
c04fcb |
\fBliblttng-ust-cyg-profile-fast.so\fR
|
|
Packit |
c04fcb |
library should only be used when it can be guaranteed that the complete event stream is recorded without any missing events, a per\-thread, stack\-based approach can be used on the trace analyzer side to match function entry and return events\&.
|
|
Packit |
c04fcb |
.RE
|
|
Packit |
c04fcb |
.SS "Verbose function tracing"
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
The following LTTng\-UST events are available when using \fBliblttng-ust-cyg-profile.so\fR\&. Their log level is set to \fBTRACE_DEBUG_FUNCTION\fR\&.
|
|
Packit |
c04fcb |
.PP
|
|
Packit |
c04fcb |
\fBlttng_ust_cyg_profile:func_entry\fR
|
|
Packit |
c04fcb |
.RS 4
|
|
Packit |
c04fcb |
Emitted when an application function is entered, or more specifically, when
|
|
Packit |
c04fcb |
\fB__cyg_profile_func_enter()\fR
|
|
Packit |
c04fcb |
is called\&.
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
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 |
T{
|
|
Packit |
c04fcb |
\fBfunc_addr\fR
|
|
Packit |
c04fcb |
T}:T{
|
|
Packit |
c04fcb |
Function address
|
|
Packit |
c04fcb |
T}
|
|
Packit |
c04fcb |
T{
|
|
Packit |
c04fcb |
\fBcall_site\fR
|
|
Packit |
c04fcb |
T}:T{
|
|
Packit |
c04fcb |
Address from which this function was called
|
|
Packit |
c04fcb |
T}
|
|
Packit |
c04fcb |
.TE
|
|
Packit |
c04fcb |
.sp 1
|
|
Packit |
c04fcb |
.RE
|
|
Packit |
c04fcb |
.PP
|
|
Packit |
c04fcb |
\fBlttng_ust_cyg_profile:func_exit\fR
|
|
Packit |
c04fcb |
.RS 4
|
|
Packit |
c04fcb |
Emitted when an application function returns, or more specifically, when
|
|
Packit |
c04fcb |
\fB__cyg_profile_func_exit()\fR
|
|
Packit |
c04fcb |
is called\&.
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
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 |
T{
|
|
Packit |
c04fcb |
\fBfunc_addr\fR
|
|
Packit |
c04fcb |
T}:T{
|
|
Packit |
c04fcb |
Function address
|
|
Packit |
c04fcb |
T}
|
|
Packit |
c04fcb |
T{
|
|
Packit |
c04fcb |
\fBcall_site\fR
|
|
Packit |
c04fcb |
T}:T{
|
|
Packit |
c04fcb |
Address from which this function was called
|
|
Packit |
c04fcb |
T}
|
|
Packit |
c04fcb |
.TE
|
|
Packit |
c04fcb |
.sp 1
|
|
Packit |
c04fcb |
.RE
|
|
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 library is part of the LTTng\-UST project\&.
|
|
Packit |
c04fcb |
.sp
|
|
Packit |
c04fcb |
This library 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 |
\fBlttng-ust\fR(3), \fBlttng\fR(1), \fBgcc\fR(1), \fBld.so\fR(8)
|