lttng-ust-cyg-profile(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | BUGS | RESOURCES | COPYRIGHTS | THANKS | AUTHORS | SEE ALSO | COLOPHON

LTTNG-UST-CYG-PRO(3)          LTTng Manual          LTTNG-UST-CYG-PRO(3)

NAME         top

       lttng-ust-cyg-profile - Function tracing (LTTng-UST helper)

SYNOPSIS         top

       Compile your application with compiler option -finstrument-
       functions.

       Launch your application by preloading liblttng-ust-cyg-profile-
       fast.so for fast function tracing:

       $ LD_PRELOAD=liblttng-ust-cyg-profile-fast.so my-app

       Launch your application by preloading liblttng-ust-cyg-profile.so
       for slower, more verbose function tracing:

       $ LD_PRELOAD=liblttng-ust-cyg-profile.so my-app

DESCRIPTION         top

       When the liblttng-ust-cyg-profile.so or the liblttng-ust-cyg-
       profile-fast.so library is preloaded before a given application
       starts, all function entry and return points are traced by
       LTTng-UST (see lttng-ust(3)), provided said application was
       compiled with the -finstrument-functions compiler option.

       See lttng(1) to learn more about how to control LTTng tracing
       sessions.

       Function tracing with LTTng-UST comes in two flavors, each one
       providing a different trade-off between performance and
       robustness:

       liblttng-ust-cyg-profile-fast.so
           This is a lightweight variant that should only be used where
           it can be guaranteed that the complete event stream is
           recorded without any missing events. Any kind of duplicate
           information is left out.

           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.

           See the Fast function tracing section below for the complete
           list of emitted events and their fields.

       liblttng-ust-cyg-profile.so
           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.

           At each function entry and exit, the address of the called
           function and the call site address are recorded in an
           LTTng-UST event.

           See the Verbose function tracing section below for the
           complete list of emitted events and their fields.

   Usage
       To use LTTng-UST function tracing, you need to make sure the
       sources of your application are compiled with the -finstrument-
       functions compiler option.

       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.

       For each instrumented function, the executable will contain calls
       to profiling function hooks (after function entry, named
       __cyg_profile_func_enter(), and just before function exit, named
       __cyg_profile_func_exit()).

       By preloading (using the LD_PRELOAD environment variable) one of
       the provided shared libraries, these profiling hooks get defined
       to emit LTTng events (as described below).

           Note

           Using this feature can result in a massive amount of trace
           data to be generated by the instrumented application.
           Application run time is also considerably affected. Be
           careful on systems with limited resources.

   Fast function tracing
       The following LTTng-UST events are available when using liblttng-
       ust-cyg-profile-fast.so. Their log level is set to
       LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_FUNCTION.

       lttng_ust_cyg_profile_fast:func_entry
           Emitted when an application function is entered, or more
           specifically, when __cyg_profile_func_enter() is called.

           Fields:
           ┌────────────┬───────────────────┐
           │ Field name Description       │
           ├────────────┼───────────────────┤
           │ func_addr  │ Function address. │
           └────────────┴───────────────────┘

       lttng_ust_cyg_profile_fast:func_exit
           Emitted when an application function returns, or more
           specifically, when __cyg_profile_func_exit() is called.

           This event has no fields. Since the liblttng-ust-cyg-profile-
           fast.so 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.

   Verbose function tracing
       The following LTTng-UST events are available when using liblttng-
       ust-cyg-profile.so. Their log level is set to
       LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_FUNCTION.

       lttng_ust_cyg_profile:func_entry
           Emitted when an application function is entered, or more
           specifically, when __cyg_profile_func_enter() is called.

           Fields:
           ┌────────────┬─────────────────────────┐
           │ Field name Description             │
           ├────────────┼─────────────────────────┤
           │ func_addr  │ Function address.       │
           ├────────────┼─────────────────────────┤
           │ call_site  │ Address from which this │
           │            │ function was called.    │
           └────────────┴─────────────────────────┘

       lttng_ust_cyg_profile:func_exit
           Emitted when an application function returns, or more
           specifically, when __cyg_profile_func_exit() is called.

           Fields:
           ┌────────────┬─────────────────────────┐
           │ Field name Description             │
           ├────────────┼─────────────────────────┤
           │ func_addr  │ Function address.       │
           ├────────────┼─────────────────────────┤
           │ call_site  │ Address from which this │
           │            │ function was called.    │
           └────────────┴─────────────────────────┘

BUGS         top

       If you encounter any issue or usability problem, please report it
       on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-
       ust>.

RESOURCES         top

       •   LTTng project website <http://lttng.org>

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

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

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

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

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

       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on
           irc.oftc.net

COPYRIGHTS         top

       This library is part of the LTTng-UST project.

       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 COPYING
       <https://github.com/lttng/lttng-ust/blob/v2.14/COPYING> file for
       more details.

THANKS         top

       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 École Polytechnique de
       Montréal for the LTTng journey.

AUTHORS         top

       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         top

       lttng-ust(3), lttng(1), gcc(1), ld.so(8)

COLOPHON         top

       This page is part of the LTTng-UST (LTTng Userspace Tracer)
       project.  Information about the project can be found at 
       ⟨http://lttng.org/⟩.  It is not known how to report bugs for this
       man page; if you know, please send a mail to man-pages@man7.org.
       This page was obtained from the tarball fetched from
       ⟨https://lttng.org/files/lttng-ust/⟩ on 2024-06-14.  If you
       discover any rendering problems in this HTML version of the page,
       or you believe there is a better or more up-to-date source for
       the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original
       manual page), send a mail to man-pages@man7.org

LTTng 2.14.0-pre               06/07/2024           LTTNG-UST-CYG-PRO(3)

Pages that refer to this page: lttng-ust(3)