CTRACK

An open-source benchmark and tracking library for C++ projects, designed to provide deep insights into function performance with minimal overhead.

CTRACK is a powerful tool that can be seamlessly integrated into both development and production environments. It allows developers to effortlessly monitor applications and identify bottlenecks, requiring minimal setup and maintenance.

Features

Single header file
No dependencies (optional tbb for non msvc to use paralell result calculation)
Easy to use (just 1 line per function you want to track)
Minimal overhead (can record tens of millions events per second)
Optimized for multi-threaded environments
Requires C++17
Compatible with major compilers out of the box
Multiple output formats (stdout(with color), string, and more soon JSON export, SQL)
Suitable for both development and high-performance production systems
Can be easily customized to filter out noise and only print events that matter. Recording levels can be adjusted based on the environment (production/development) to balance between insight and performance.
Includes a beautiful table print functionality for clear and readable output. While easy-to-use functions are provided for accessing CTRACK events, more experienced users can access all data directly for advanced analysis.

Goals

Help developers identify areas for performance improvement
Monitor application performance in production

Basic Usage

CTRACK is easy to use and provides powerful performance insights. Here's how to get started:

To track a function, simply add the CTRACK; macro at the beginning of the function body:

void myFunction() {
    CTRACK;
    // Your function code here
}

To print the results, you have two options:

a. Print colored results to the console:
```
ctrack::result_print();
```
b. Get the results as a string (useful for logging or custom output):
```
std::string results = ctrack::result_as_string();
```

Important: Scope-Based Tracking

CTRACK uses RAII (Resource Acquisition Is Initialization) to track function execution times. Events are recorded when the CTRACK object goes out of scope. This has an important implication:

int main() {
    CTRACK;  // This won't track main() completely!
    doWork();
    ctrack::result_print();  // CTRACK is still in scope here
    return 0;  // CTRACK records here when main() exits
}

To properly track a section of code within a function, use explicit scoping:

int main() {
    {
        CTRACK;  // Start tracking
        doWork();
    }  // CTRACK goes out of scope and records the event

    ctrack::result_print();  // Now we can see the results
    return 0;
}

Example

#include "ctrack.hpp"

void expensiveOperation() {
    CTRACK;
    // Simulating some work
    for (int i = 0; i < 1000000; ++i) {
        // Do something
    }
}

int main() {
    {
        CTRACK;  // Track this block
        for (int i = 0; i < 100; ++i) {
            expensiveOperation();
        }
    }  // CTRACK records here

    // Print results to console
    ctrack::result_print();

    return 0;
}

This basic usage will automatically track the performance of expensiveOperation and the main loop block, providing you with insights when you call result_print().

For more complex scenarios, configuration options, and advanced features, please refer to the Advanced Usage section below. Additionally, be sure to check out the examples directory in the repository for more detailed usage examples and best practices.

Metrics & Output

CTRACK provides comprehensive performance metrics through two main components: the Summary Table and the Detail Table. These tables offer different levels of insight into your application's performance.

Time Units

All times in CTRACK are presented and automatically converted in easily understandable units:

ns (nanoseconds)
μs (microseconds) printed as mcs
ms (milliseconds)
s (seconds)

General Metrics

min, mean, med, max: The fastest (min), average (mean), median (med), and slowest (max) execution times for a specific CTRACK event.
time a - time active: Total time the event was active, useful for multithreaded environments. For example, if a 100ms function is called by 10 threads simultaneously, time active will show 100ms instead of 1000ms.
time ae - time active exclusive: Subtracts the time spent in child functions that are also tracked. Intelligently handles recursion and overlapping timeframes.
time [x-y]: Shows event times within specified percentile ranges (default [0-100] and [1-99]) to exclude outliers.
sd - Standard Deviation: Displays the variability in function execution times.
cv - Coefficient of Variation: Unitless version of standard deviation (sd / mean) for comparing variability across functions with different scales.
time acc: Simple sum of execution times for all calls to a tracked function.
threads: Number of different threads that called a specific function.

Summary Table

Summary Header

Start and End time of tracking
Total time
Time tracked (time spent in tracked functions)
Time tracked percentage

Summary Entries

Filename, function, line
Number of calls
Time active exclusive for [0-100] and [center interval] (in percent and absolute)
Time active for [0-100] in absolute

The summary table is sorted by the active exclusive [center interval] metric.

Detail Table

For each function:

Filename, function, line
Time accumulated
Standard Deviation
Coefficient of Variation (cv)
Number of calls
Number of calling threads

Each entry shows 3 blocks for the fastest, center, and slowest events.

Output Format

String output: Summary table followed by Detail tables (slowest to fastest)
Console output: Reversed order (Detail tables followed by Summary table)

This comprehensive set of metrics allows for deep insight into your application's performance, helping you identify bottlenecks and optimize effectively.

For more advanced usage and customization options, please refer to the Advanced Usage section below.

Installation

CTRACK is designed to be easy to integrate into your C++ projects. There are two primary ways to use CTRACK:

1. Header-Only Inclusion

CTRACK is a header-only library, which means you can start using it by simply including the main header file in your project:

#include "ctrack.hpp"

This method is straightforward and doesn't require any additional setup or build process.

Note: If you are using a compiler which needs TBB for C++ standard parallel algorithms, you need to link to -ltbb. You can always fall back to sequential result calculation by setting CTRACK_DISABLE_EXECUTION_POLICY. The recording will be unchanged, but the printing/calculating of the stats will be a bit slower.

2. CMake Package

For projects using CMake, CTRACK can be installed and used as a CMake package. This method provides better integration with your build system and makes it easier to manage dependencies.

To use CTRACK as a CMake package:

Install CTRACK using CMake:

git clone https://github.com/your-repo/ctrack.git
cd ctrack
mkdir build && cd build
cmake ..
cmake --build . --target install

In your project's CMakeLists.txt, add:

find_package(ctrack REQUIRED)
target_link_libraries(your_target PRIVATE ctrack::ctrack)

Note: If you are using a compiler which needs TBB for C++ standard parallel algorithms, you need to link to tbb. target_link_libraries( your_target PRIVATE TBB::tbb ) You can always fall back to sequential result calculation by setting CTRACK_DISABLE_EXECUTION_POLICY. The recording will be unchanged, but the printing/calculating of the stats will be a bit slower.

For more detailed examples of how to use CTRACK with CMake, please refer to the examples directory in the CTRACK repository.

Choose the installation method that best fits your project's needs and structure. Both methods provide full access to CTRACK's features and capabilities.

Advanced Usage

Customizing Output Settings

You can fine-tune CTRACK's output using the ctrack_result_settings struct:

struct ctrack_result_settings {
    unsigned int non_center_percent = 1;
    double min_percent_active_exclusive = 0.5; // between 0-100, default 0.5%
    double percent_exclude_fastest_active_exclusive = 0.0; // between 0-100
};

non_center_percent: Defines the range for the center interval (e.g., 1 means [1-99])
min_percent_active_exclusive: Excludes events active for less than the specified percentage
percent_exclude_fastest_active_exclusive: Excludes the fastest n% of functions to reduce noise

Advanced CTRACK Calls

CTRACK offers different tracking levels:

CTRACK: Standard tracking
CTRACK_DEV: Development-specific tracking
CTRACK_PROD: Production-specific tracking

You can selectively disable tracking groups:

CTRACK_DISABLE_DEV: Disables all CTRACK_DEV calls

To completely disable CTRACK at compile time, define CTRACK_DISABLE.

Custom Naming

Use custom names for CTRACK calls instead of function names:

CTRACK_NAME("myname")
CTRACK_DEV_NAME("mydevname")
CTRACK_PROD_NAME("myprodname")

This is useful for large functi

Ctrack

Install / Use

README