LTTNG-UST-CYG-PRO(3)

💅 NAME

lttng-ust-cyg-profile — function tracing, but make it LTTng-UST helper energy ✨

This one lives in the LTTng Manual, bestie, and it's page LTTNG-UST-CYG-PRO(3).

---

🎀 SYNOPSIS

Okay so step one: compile your application with the compiler option -finstrument-functions. Non-negotiable, that's the whole vibe.

Then launch your app by preloading liblttng-ust-cyg-profile-fast.so for that fast function tracing life:

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

Or launch it by preloading liblttng-ust-cyg-profile.so if you want the slower, more verbose function tracing (she tells you everything, and I mean everything):

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

---

🦋 DESCRIPTION

So here's the tea: when either the liblttng-ust-cyg-profile.so library or the liblttng-ust-cyg-profile-fast.so library gets preloaded before a given application starts, every single function entry and return point gets traced by LTTng-UST (peep lttng-ust(3)) — provided said application was compiled with the -finstrument-functions compiler option. That's the catch, that's the prerequisite, no cap.

Wanna know how to control LTTng tracing sessions? Go read lttng(1), she'll sort you out.

Function tracing with LTTng-UST comes in two flavors, each one giving you a different trade-off between performance and robustness. It's giving pick your fighter:

• liblttng-ust-cyg-profile-fast.so — this is the lightweight variant, and you should only use her where it can be guaranteed that the complete event stream is recorded without any missing events. Any kind of duplicate information is left out — she does not do redundancy, she's that girl.

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.

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

• liblttng-ust-cyg-profile.so — this is the more robust variant, and she 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. She's the friend who brings receipts. 🧾

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

Scroll to 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. Like, actually make sure. Not "I think I did" make sure.

It might be necessary to limit the number of source files where this option is used to prevent an excessive amount of trace data from being generated at run time. Bestie. The trace data. It's a lot. Usually, there are additional compiler flags that allow you to specify a more fine-grained selection of function instrumentation, so use them, iykyk.

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). Slay.

⚠️ Note: using this feature can result in a massive amount of trace data being generated by the instrumented application. Application run time is also considerably affected. Be careful on systems with limited resources — fr fr, do not do this on a tiny box and then act surprised. 💀

🎀 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:

• 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. Cute, efficient, iconic. ✨

💜 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:

• 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:

• 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: https://bugs.lttng.org/projects/lttng-ust

Don't suffer in silence, bestie, that's not the move. 🫶

---

🌈 RESOURCES

• 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

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

---

⭐ THANKS

Thanks to Ericsson for funding this work, providing real-life use cases, and testing. Genuinely, thank you. 💖

Special thanks to Michel Dagenais and the DORSAL laboratory — http://www.dorsal.polymtl.ca/ — at École Polytechnique de Montréal for the LTTng journey. The way that whole journey ate. 🦋

---

🧚 AUTHORS

LTTng-UST was originally written by Mathieu Desnoyers, with additional contributions from various other people. It is currently maintained by Mathieu Desnoyers — mathieu.desnoyers@efficios.com

---

🔥 SEE ALSO

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

---

That's the whole page, bestie — go instrument something and hydrate. 💅

LTTng 2.16.0, dated 08/27/2026 — catch you on the flip side, mwah 🎀