FuncStalker

FuncStalker is a C++ In-Code Profiler designed to capture the entry and exit points of all functions in your code. The collected data is stored in a JSON report, named funcstalker_report_<timestamp>.json.

Installation

To install FuncStalker, execute the following steps:

# Create a build directory and navigate to it
mkdir build
cd build

# Generate build files
cmake -G "Unix Makefiles" .. -DCMAKE_BUILD_TYPE=Release

# Build and install
sudo cmake --build . --target install -- -j$(nproc)

Usage

1. Including FuncStalker in Your Project

Start by locating and including the FuncStalker package in your CMake project:

find_package(FuncStalker REQUIRED)

2. Configuring Targets

• For Executables

  To profile an executable, link FuncStalker to your target using:

    add_executable(myProgram [...])
    target_link_libraries(myProgram PRIVATE FuncStalker::FuncStalker)

• For Static Libraries (Note: Shared library profiling is not supported)

  If you need profiling for static libraries:

  • For library-only profiling

        add_library(mylibrary STATIC [...])
        target_link_libraries(mylibrary PRIVATE FuncStalker::FuncStalker)

    (don't forget to activate and deactivate profiling manually in your code)

  • To include higher-level targets in profiling:

        target_link_libraries(mylibrary PUBLIC FuncStalker::FuncStalker)

3. Excluding Specific Locations

To exclude certain file paths from profiling (besides default excluded paths — usr/ and usr/local/), add the paths to the compiler options:

target_compile_options(
    myTarget 
    PRIVATE or PUBLIC 
    -finstrument-functions-exclude-file-list="/path/to/be/ignored"
)

Using the Library

Automatic Profiling

To enable automatic profiling, declare the following in your code:

extern "C" bool __funcstalker_auto{true};

Manual Profiling

For manual control, follow these steps:

1. Disable automatic profiling:

       extern "C" bool __funcstalker_auto{false};

2. Manually start and stop profiling using the provided functions in <funcstalker/funcstalker.h>:

       funcstalker_start();
       funcstalker_stop();

Report Format

The profiling output is a JSON array of objects. Each object represents a single function event (either entry or exit) and contains the following fields:

• ts: Elapsed time in nanoseconds since profiling started (type: number).
• func: Fully qualified name of the function (type: string).
• tid: Thread ID used to distinguish between function calls (type: number).
• exit: Boolean flag indicating whether the event is a function exit (true) or function entry (false).

Example Report

[
  {
    "ts": 0,
    "func": "main",
    "tid": 3598237495,
    "exit": false
  },
  {
    "ts": 1111,
    "func": "MyNamespace::MyClass::MyFunction",
    "tid": 2453467777,
    "exit": false
  },
  {
    "ts": 2222,
    "func": "MyNamespace::MyClass::MyFunction",
    "tid": 2453467777,
    "exit": true
  },
  {
    "ts": 3333,
    "func": "main",
    "tid": 3598237495,
    "exit": true
  }
]

Each object provides a precise snapshot of a single event, making it easy to track function call order and timing across threads.