Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/amzn/hawktracer
HawkTracer is a highly portable, low-overhead, configurable profiling tool built in Amazon Video for getting performance metrics from low-end devices.
https://github.com/amzn/hawktracer
hacktoberfest instrumentation performance performance-monitoring
Last synced: 3 days ago
JSON representation
HawkTracer is a highly portable, low-overhead, configurable profiling tool built in Amazon Video for getting performance metrics from low-end devices.
- Host: GitHub
- URL: https://github.com/amzn/hawktracer
- Owner: amzn
- License: mit
- Created: 2018-04-10T00:17:00.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-08-30T08:14:27.000Z (about 1 year ago)
- Last Synced: 2023-11-07T16:10:42.808Z (about 1 year ago)
- Topics: hacktoberfest, instrumentation, performance, performance-monitoring
- Language: C++
- Homepage:
- Size: 1.06 MB
- Stars: 131
- Watchers: 12
- Forks: 35
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://travis-ci.org/amzn/hawktracer)
[](https://gitter.im/amzn/hawktracer)
[](https://www.codacy.com/app/loganek/hawktracer?utm_source=github.com&utm_medium=referral&utm_content=loganek/hawktracer&utm_campaign=Badge_Grade)
[](https://codecov.io/gh/loganek/hawktracer)
[](https://ci.appveyor.com/project/loganek/hawktracer)
# HawkTracer
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**](bindings/python3) and [**Rust**](https://github.com/AlexEne/rust_hawktracer).
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.
## Features
* 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)
## License Summary
This sample code is made available under the MIT license.
(See [LICENSE](LICENSE) file)
## Getting Started
### Hello World! tutorials
See [the tutorial](https://hawktracer.github.io/doc/stable/tutorial_hello_world.html) to quickly onboard to HawkTracer or check the [examples](examples/) directory.
The tutorial step by step explains how to build and instrument the code like that:
```cpp
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.
### Building library
```bash
$ 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 Windows
```
## Attaching HawkTracer to a project to profile
### Build system integration
#### CMake-based projects
If you use CMake build system, you can use following code to attach HawkTracer library to your project:
```cmake
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)
```
#### pkg-config
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:
```bash
$ g++ my_project.cpp $(pkg-config --cflags --libs hawktracer)
```
### Instrumenting code
#### Initialize library
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:
```cpp
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](#collect-the-data)).
#### Instrumenting the code
HawkTracer requires explicit code instrumentation. The library provides a few helper macros for reporting data to a timeline:
```cpp
// 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_`:
```cpp
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:
```cpp
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();
}
}
```
### Collect the data
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:
```bash
hawktracer-to-json --source file_name.htdump --output output_file.json
```
### Analyzing the data
* Install google-chrome or chromium browser
* Open the browser, and open [chrome://tracing/](chrome://tracing) webpage
* Click load button and open file generated in the previous section
* You should see a callstack with timing
## Contributing
Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.
## Acknowledgment
* Hat tip to anyone who's code was used
* Inspiration
* etc