Intel® Trace Collector 9.1 Update 2 User and Reference Guide

Tracing Library Calls

If you have an application that makes heavy use of libraries or software components developed independently, you may want to exclude the information not related directly to your application from the trace data. At the same time, the library developer might want to do the opposite – trace only data related to their library.

Intel® Trace Collector provides a capability to turn off tracing for functions at a certain call stack level, that is to fold them. If you want to trace calls within the folded functions, you can unfold them.

To enable folding, use the FOLD and UNFOLD keywords for the STATE, SYMBOL or ACTIVITY configuration options to select functions for folding by their name (SYMBOL), class (ACTIVITY) or both (STATE). Use the CALLER keyword to specify the function caller. See Filtering Trace Data for details on syntax.

Note

To enable Intel® Trace Collector to profile non-MPI functions, make sure to instrument them using the compiler instrumentation or API. See Tracing User Defined Events.

Below are examples of folding for the application with four additional libraries.

General Structure of an Application Using Multiple Libraries

From the figure above, the following information may be of interest for the application and the library developers:

Application developer

Library developer

The lib2 developer will need information about the calls from the application, to component libraries (lib3 and lib4), and to system-level services (MPI). They will have no interest in performance data for lib1. The lib1 developer will have no interest in data from lib2, lib3, and lib4.

Examples

In this section folding is illustrated by giving configurations that apply to the example above. The C program available at examples/libraries.c reproduces the same pattern. Its call tree looks as follows (calls are aggregated and sorted by name, therefore the order is not sequential):

By using the configuration options listed below, different parties can run the same executable to get different traces:

Application developer: Trace the application only with the top-level calls in lib1, lib2, and lib4.

Configuration file: examples/run_splibraries_app.conf

STATE lib*:* FOLD

Call tree:

lib2 developer: Trace only calls in lib2, including its top-level calls

Configuration file: examples/run_splibraries_lib2.conf

Call tree:

lib2 Developer, detailed view: Trace the top-level calls to lib2 and all lib2, lib3, lib4 and system services invoked by them

Configuration file: examples/run_splibraries_lib2detail.conf

STATE Application:* FOLD
STATE lib2:* UNFOLD

Call tree:

Application and lib4 Developers: Trace the calls in lib4 only made by the application

Configuration file: examples/run_splibraries_lib4.conf

STATE *:* FOLD
STATE lib4:* UNFOLD CALLER Application:*

Call tree:

It is assumed that the application, library and system calls are instrumented in the way that their classes are different. Alternatively, you can match against the function name prefix that is shared by all library calls in the same library.