HawkTracer is a highly portable, low-overhead, configurable profiling tool built in Amazon Video for getting performance metrics from low-end devices.
HawkTracer is available on most popular platforms: Linux, Windows, OS X. By default, the library can be used with C and C++, but there are also wrappers for Python and Rust.
The library provides many different types of events (e.g. CPU usage event, duration tracepoint), but the list can easily be extended by the user.
- Low CPU/memory overhead
- Multi-platform
- Highly configurable on runtime
- Easy build integration (CMake & pkg-config files)
- Pre-defined and user-defined events
- Simple macros for code instrumentation
- Streaming events to file, through TCP/IP protocol, or handling them in custom function
- Client for receiving event stream
- Library for parsing event stream (so you can write your own client)
This sample code is made available under the MIT license. (See LICENSE file)
See the tutorial to quickly onboard to HawkTracer or check the examples directory. The tutorial step by step explains how to build and instrument the code like that:
static void hello_world()
{
HT_G_TRACE_FUNCTION()
for (int i = 0; i < 100; i++)
{
HT_TP_G_STRACEPOINT("iteration")
printf("2 * %d = %d\n", i, 2*i);
std::string txt = "Iteration (mod 10): " + std::to_string(i % 10);
HT_TP_G_DYN_STRACEPOINT(txt.c_str());
printf("text: %s\n", txt.c_str());
}
}You can also follow instructions below to get HawkTracer up and running.
$ mkdir build # It'll be different on Windows
$ cd build
$ cmake ..
$ cmake --build . # This instead of make, so we don't need extra instructions for WindowsIf you use CMake build system, you can use following code to attach HawkTracer library to your project:
project(your_project)
# optionally, you might define a path to HawkTracer's CMake module
# CMake the path below should be a path to a directory where HawkTracerConfig.cmake is located, e.g.:
# list(APPEND CMAKE_MODULE_PATH "/usr/local/lib/cmake/HawkTracer")
find_package(HawkTracer REQUIRED)
add_executable(your_project main.cc)
target_link_libraries(your_project HawkTracer::hawktracer)
HawkTracer library provides pkg-config file which can be used to find required libraries and include paths. You can simply integrate it e.g. with your compilation command:
$ g++ my_project.cpp $(pkg-config --cflags --libs hawktracer)Before you start profiling your code, you need to initialize HawkTracer library. There are 2 functions which always have to be called in projects profiled by HawkTracer: ht_init and ht_deinit.
Additionally, you need to specify an event listener. HawkTracer currently provides 2 listeners:
- TCP listener, which streams events over the network
- File dump listener, which saves events to a file.
Moreover, HawkTracer allows to provide user-defined listeners. Code below presents example HawkTracer (un)initialization:
int main(int argc, char** argv)
{
ht_init(argc, argv); // initialize library
HT_Timeline* timeline = ht_global_timeline_get(); // timeline, where all events are posted. You can define your own timeline, or use global timeline
const size_t buffer_size = 4096; // size of internal listener's buffer
ht_file_dump_listener_register(ht_global_timeline_get(), "hello-world-out.htdump", 2048, NULL); // create listener and attach it to timeline
// your code goes here...
ht_deinit(); // uninitialize library
return 0;
}
The code registers file dump listener, which saves all the events to a file file_name.htdump. The file should be then converted to a viewer's format (see here for details).
HawkTracer requires explicit code instrumentation. The library provides a few helper macros for reporting data to a timeline:
// Pushes any type of event to a timeline
HT_TIMELINE_PUSH_EVENT(TIMELINE, EVENT_TYPE, EVENT_PARAMETERS,...)
// Reports a duration of specific block of code (available only for C++ or C GNU compiler)
HT_TRACE(TIMELINE, LABEL)
// The same as above, but automatically sets label to current function name
HT_TRACE_FUNCTION(TIMELINE)There are few macros which report events to a global timeline, they're prefixed with G_:
HT_G_TRACE(LABEL)
HT_G_TRACE_OPT_STATIC(LABEL)
HT_G_TRACE_OPT_DYNAMIC(LABEL)
HT_G_TRACE_FUNCTION()For example, you can instrument following code:
void foo()
{
HT_G_TRACE_FUNCTION() // measure duration of foo function execution
for (int i = 0; i < 100; i++)
{
HT_G_TRACE_OPT_STATIC("in-loop") // measure duration of single loop iteration
bar();
}
}For now HawkTracer provides a simple application for converting event stream to a JSON format which can be consumed by the viewing application: hawktracer-to-json. You can use it with a file or with a network stream. Assuming your events have been saved to file_name.htdump file, you can generate the JSON file running following command:
hawktracer-to-json --source file_name.htdump --output output_file.json- Install google-chrome or chromium browser
- Open the browser, and open chrome://tracing/ webpage
- Click load button and open file generated in the previous section
- You should see a callstack with timing
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
- Hat tip to anyone who's code was used
- Inspiration
- etc
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent