Name: hawktracer
Owner: Amazon
Description: HawkTracer is a highly portable, low-overhead, configurable profiling tool built in Amazon Video for getting performance metrics from low-end devices.
Created: 2018-04-10 00:17:00.0
Updated: 2018-05-24 20:09:46.0
Pushed: 2018-05-24 20:09:45.0
Homepage: null
Size: 1151
Language: C++
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
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. The library can be used with C and C++.
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.
This sample code is made available under the MIT license. (See LICENSE file)
dir build # It'll be different on Windows
ake ..
ake --build . # This instead of make, so we don't need extra instructions for Windows
If you use CMake build system, you can use following code to attach HawkTracer library to your project:
ect(your_project)
tionally, you might define a path to HawkTracer's CMake module
ake the path below should be a path to a directory where HawkTracerConfig.cmake is located, e.g.:
st(APPEND CMAKE_MODULE_PATH "/usr/local/lib/cmake/HawkTracer")
_package(HawkTracer REQUIRED)
executable(your_project main.cc)
et_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:
+ 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:
Moreover, HawkTracer allows to provide user-defined listeners. Code below presents example HawkTracer (un)initialization:
main(int argc, char** argv)
_init(argc, argv); // initialize library
_Timeline* timeline = ht_global_timeline_get(); // timeline, where all events are posted. You can define your own timeline, or use global timeline
_FileDumpListener* listener = ht_file_dump_listener_create("file_name.htdump", buffer_size, NULL); // initialize listener
nst size_t buffer_size = 4096; // size of internal listener's buffer
_timeline_register_listener(timeline, ht_file_dump_listener_callback, listener); // register listener to a timeline
your code goes here...
_timeline_flush(timeline); // flush all remaining events from timeline
_timeline_unregister_all_listeners(timeline); // unregister listeners from timeline
_file_dump_listener_destroy(listener); // deinitialize listener
_deinit(); // uninitialize library
turn 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:
ushes any type of event to a timeline
IMELINE_PUSH_EVENT(TIMELINE, EVENT_TYPE, EVENT_PARAMETERS,...)
eports a duration of specific block of code (available only for C++ or C GNU compiler)
P_STRACEPOINT(TIMELINE, LABEL)
he same as above, but automatically sets label to current function name
P_FUNCTION(TIMELINE)
There are few macros which report events to a global timeline, they're prefixed with G_:
P_G_STRACEPOINT(LABEL)
P_G_FUNCTION()
For example, you can instrument following code:
foo()
_TP_G_FUNCTION() // measure duration of foo function execution
r (int i = 0; i < 100; i++)
HT_TP_G_STRACEPOINT("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:
tracer-to-json --source file_name.htdump --output output_file.json
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.