Lightweight cross-platform profiler library for c++
You can profile any function in you code. Furthermore this library provide measuring time of any block of code. For example, information for 12 millions of blocks is using less than 300Mb of memory. Working profiler slows your application execution for only 1-2%.
Average overhead per block is about 15ns/block (tested on Intel Core i7-5930K 3.5GHz, Win7)
Disabled profiler will not affect your application execution in any way. You can leave it in your Release build and enable it at run-time at any moment during application launch to see what is happening at the moment.
Also the library can capture system's context switch events between threads. Context switch information includes duration, target thread id, thread owner process id, thread owner process name.
You can see the results of measuring in simple GUI application which provides full statistics and renders beautiful time-line.
Profiling CryEngine SDK example
New UI style in version 2.0
First of all you can specify path to include directory which contains include/profiler
directory and define macro BUILD_WITH_EASY_PROFILER
.
For linking with easy_profiler you can specify path to library.
If you are using cmake
set CMAKE_PREFIX_PATH
to lib/cmake/easy_profiler
directory (from release package) and use function find_package(easy_profiler)
with target_link_libraries(... easy_profiler)
.
Example:
project(my_application)
set(SOURCES
main.cpp
)
# CMAKE_PREFIX_PATH should be set to <easy_profiler-release_dir>/lib/cmake/easy_profiler
find_package(easy_profiler REQUIRED) # STEP 1 #########################
add_executable(my_application ${SOURCES})
target_link_libraries(my_application easy_profiler) # STEP 2 ##########
Example of usage.
#include <easy/profiler.h>
void foo() {
EASY_FUNCTION(profiler::colors::Magenta); // Magenta block with name "foo"
EASY_BLOCK("Calculating sum"); // Begin block with default color == Amber100
int sum = 0;
for (int i = 0; i < 10; ++i) {
EASY_BLOCK("Addition", profiler::colors::Red); // Scoped red block (no EASY_END_BLOCK needed)
sum += i;
}
EASY_END_BLOCK; // End of "Calculating sum" block
EASY_BLOCK("Calculating multiplication", profiler::colors::Blue500); // Blue block
int mul = 1;
for (int i = 1; i < 11; ++i)
mul *= i;
//EASY_END_BLOCK; // This is not needed because all blocks are ended on destructor when closing braces met
}
void bar() {
EASY_FUNCTION(0xfff080aa); // Function block with custom ARGB color
}
void baz() {
EASY_FUNCTION(); // Function block with default color == Amber100
}
EasyProfiler is using Google Material-Design colors palette, but you can use custom colors in ARGB format (like shown in example above).
The default color is Amber100
(it is used when you do not specify color explicitly).
Example of storing variables:
#include <easy/profiler.h>
#include <easy/arbitrary_value.h> // EASY_VALUE, EASY_ARRAY are defined here
class Object {
Vector3 m_position; // Let's suppose Vector3 is a struct { float x, y, z; };
unsigned int m_id;
public:
void act() {
EASY_FUNCTION(profiler::colors::Cyan);
// Dump variables values
constexpr auto Size = sizeof(Vector3) / sizeof(float);
EASY_VALUE("id", m_id);
EASY_ARRAY("position", &m_position.x, Size, profiler::color::Red);
// Do something ...
}
void loop(uint32_t N) {
EASY_FUNCTION();
EASY_VALUE("N", N, EASY_VIN("N")); /* EASY_VIN is used here to ensure
that this value id will always be
the same, because the address of N
can change */
for (uint32_t i = 0; i < N; ++i) {
// Do something
}
}
};
There are two ways to collect profiling data: streaming over network and dumping data to file.
This is the most preferred and convenient method in many cases.
profiler::startListen()
. This will start new thread to listen 28077
port for the start-capture-signal from profiler_gui.hostname
or IP-address
.Start capture
button in profiler_gui.Stop capture
button in profiler_gui to stop capturing and wait until profiled data will be passed over network.profiler::stopListen()
to stop listening. Example:
void main() {
profiler::startListen();
/* do work */
}
EASY_PROFILER_ENABLE
macro somewhere into the code.profiler::dumpBlocksToFile("test_profile.prof")
function.Example:
void main() {
EASY_PROFILER_ENABLE;
/* do work */
profiler::dumpBlocksToFile("test_profile.prof");
}
To capture a thread context-switch events you need:
systemtap
script with root privileges as follow (example on Fedora):
#stap -o /tmp/cs_profiling_info.log scripts/context_switch_logger.stp name APPLICATION_NAME
APPLICATION_NAME - name of your application
There are some known issues on a linux based systems (for more information see wiki)
To profile your application startup (when using network method) add EASY_PROFILER_ENABLE
macro into the code together with profiler::startListen()
.
Example:
void main() {
EASY_PROFILER_ENABLE;
profiler::startListen();
/* do work */
}
This will allow you to collect profiling data before profiler_gui connection. profiler_gui will automatically display capturing dialog window after successful connection to the profiled application.
thread_local
support is highly recommended: GCC >=4.8, Clang >=3.3Additional requirements for GUI:
$ mkdir build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE="Release" ..
$ make
$ mkdir build
$ cd build
$ cmake -DCMAKE_CXX_COMPILER=g++-5 -DCMAKE_C_COMPILER=gcc-5 -DCMAKE_BUILD_TYPE="Release" ..
$ make
If you are using QtCreator IDE you can just open CMakeLists.txt
file in root directory.
If you are using Visual Studio you can generate solution by cmake generator command.
Examples shows how to generate Win64 solution for Visual Studio 2013. To generate for another version use proper cmake generator (-G "name of generator").
Specify path to cmake scripts in Qt5 dir (usually in lib/cmake subdir) and execute cmake generator command, for example:
$ mkdir build
$ cd build
$ cmake -DCMAKE_PREFIX_PATH="C:\Qt\5.3\msvc2013_64\lib\cmake" .. -G "Visual Studio 12 2013 Win64"
Create system variable "Qt5Widgets_DIR" and set it's value to "[path-to-Qt5-binaries]\lib\cmake\Qt5Widgets". For example, "C:\Qt\5.3\msvc2013_64\lib\cmake\Qt5Widgets". And then run cmake generator as follows:
$ mkdir build
$ cd build
$ cmake .. -G "Visual Studio 12 2013 Win64"
$ souce $QNX_ENVIRONMENT
$ mkdir build
$ cd build
$ cmake -DCMAKE_TOOLCHAIN_FILE=/path/to/QNXToolchain.cmake ..
For more information and example for QNXToolchain.cmake
see this PR
You can build native library for android by using NDK and standalone toolchain. See comment for this PR to get a more detailed instruction.
Branch develop
contains all v2.0.0 features and new UI style.
Please, note that .prof file header has changed in v2.0.0:
struct EasyFileHeader {
uint32_t signature = 0;
uint32_t version = 0;
profiler::processid_t pid = 0;
int64_t cpu_frequency = 0;
profiler::timestamp_t begin_time = 0;
profiler::timestamp_t end_time = 0;
// Changed order of memory_size and blocks_number relative to v1.3.0
uint64_t memory_size = 0;
uint64_t descriptors_memory_size = 0;
uint32_t total_blocks_number = 0;
uint32_t total_descriptors_number = 0;
};
Licensed under either of
at your option.