--- name: "lttng-ust-cyg-profile" section: "3" platform: "linux" package: "lttng-ust" version: "2.16.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/lttng-ust-cyg-profile" --- # lttng-ust-cyg-profile(3) Function tracing (LTTng-UST helper) ## NAME lttng-ust-cyg-profile - Function tracing (LTTng-UST helper) ## SYNOPSIS 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 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)](/lttng-ust/3.md)), provided said application was compiled with the **-finstrument-functions** compiler option. See [**lttng**(1)](/lttng/1.md) 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 If you encounter any issue or usability problem, please report it on the LTTng bug tracker \. ## RESOURCES • LTTng project website \ • LTTng documentation \ • Git repositories \ • GitHub organization \ • Continuous integration \ • Mailing list \ for support and development: **lttng-dev@lists.lttng.org** • IRC channel \: **#lttng** on **irc.oftc.net** ## COPYRIGHTS This library is part of the LTTng-UST project. This library is distributed under the GNU Lesser General Public License, version 2.1 \. See the **COPYING** \ file for more details. ## THANKS Thanks to Ericsson for funding this work, providing real-life use cases, and testing. Special thanks to Michel Dagenais and the DORSAL laboratory \ at École Polytechnique de Montréal for the LTTng journey. ## AUTHORS LTTng-UST was originally written by Mathieu Desnoyers, with additional contributions from various other people. It is currently maintained by Mathieu Desnoyers \. ## SEE ALSO [**lttng-ust**(3)](/lttng-ust/3.md), [**lttng**(1)](/lttng/1.md), [**gcc**(1)](/gcc/1.md), [**ld.so**(8)](/ld.so/8.md)