{"id":19646630,"url":"https://github.com/amzn/hawktracer","last_synced_at":"2025-06-11T17:37:54.581Z","repository":{"id":49524366,"uuid":"128848910","full_name":"amzn/hawktracer","owner":"amzn","description":"HawkTracer is a highly portable, low-overhead, configurable profiling tool built in Amazon Video for getting performance metrics from low-end devices.","archived":false,"fork":false,"pushed_at":"2023-08-30T08:14:27.000Z","size":1111,"stargazers_count":134,"open_issues_count":24,"forks_count":31,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-05T09:22:38.996Z","etag":null,"topics":["hacktoberfest","instrumentation","performance","performance-monitoring"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amzn.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-10T00:17:00.000Z","updated_at":"2025-02-16T09:24:32.000Z","dependencies_parsed_at":"2024-11-11T14:41:18.767Z","dependency_job_id":"0baff7b8-8aa1-405d-b545-d5d6c921fc4a","html_url":"https://github.com/amzn/hawktracer","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amzn%2Fhawktracer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amzn%2Fhawktracer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amzn%2Fhawktracer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amzn%2Fhawktracer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amzn","download_url":"https://codeload.github.com/amzn/hawktracer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251338560,"owners_count":21573578,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","instrumentation","performance","performance-monitoring"],"created_at":"2024-11-11T14:39:33.890Z","updated_at":"2025-04-28T15:30:48.558Z","avatar_url":"https://github.com/amzn.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/amzn/hawktracer.svg?branch=master)](https://travis-ci.org/amzn/hawktracer)\n[![Gitter chat](https://img.shields.io/gitter/room/amzn/hawktracer.svg)](https://gitter.im/amzn/hawktracer)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/8d0f18c7a6b14f15bb747b0a4cd336bb)](https://www.codacy.com/app/loganek/hawktracer?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=loganek/hawktracer\u0026amp;utm_campaign=Badge_Grade)\n[![codecov](https://codecov.io/gh/loganek/hawktracer/branch/master/graph/badge.svg)](https://codecov.io/gh/loganek/hawktracer)\n[![Build status](https://ci.appveyor.com/api/projects/status/3yh0rvyxs0x38802?svg=true)](https://ci.appveyor.com/project/loganek/hawktracer)\n\n# HawkTracer\n\nHawkTracer is a highly portable, low-overhead, configurable profiling tool built in Amazon Video for getting performance metrics from low-end devices.\n\nHawkTracer 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).\n\nThe library provides many different types of events (e.g. CPU usage event, duration tracepoint), but the list can easily be extended by the user.\n\n## Features\n* Low CPU/memory overhead\n* Multi-platform\n* Highly configurable on runtime\n* Easy build integration (CMake \u0026 pkg-config files)\n* Pre-defined and user-defined events\n* Simple macros for code instrumentation\n* Streaming events to file, through TCP/IP protocol, or handling them in custom function\n* Client for receiving event stream\n* Library for parsing event stream (so you can write your own client)\n\n## License Summary\n\nThis sample code is made available under the MIT license.\n(See [LICENSE](LICENSE) file)\n\n## Getting Started\n\n### Hello World! tutorials\nSee [the tutorial](https://hawktracer.github.io/doc/stable/tutorial_hello_world.html) to quickly onboard to HawkTracer or check the [examples](examples/) directory.\nThe tutorial step by step explains how to build and instrument the code like that:\n```cpp\nstatic void hello_world()\n{\n    HT_G_TRACE_FUNCTION()\n\n    for (int i = 0; i \u003c 100; i++)\n    {\n        HT_TP_G_STRACEPOINT(\"iteration\")\n        printf(\"2 * %d = %d\\n\", i, 2*i);\n\n        std::string txt = \"Iteration (mod 10): \" + std::to_string(i % 10);\n        HT_TP_G_DYN_STRACEPOINT(txt.c_str());\n        printf(\"text: %s\\n\", txt.c_str());\n    }\n}\n```\nYou can also follow instructions below to get HawkTracer up and running.\n\n### Building library\n```bash\n$ mkdir build       # It'll be different on Windows\n$ cd build\n$ cmake ..\n$ cmake --build .   # This instead of make, so we don't need extra instructions for Windows\n```\n\n## Attaching HawkTracer to a project to profile\n\n### Build system integration\n\n#### CMake-based projects\nIf you use CMake build system, you can use following code to attach HawkTracer library to your project:\n```cmake\nproject(your_project)\n\n# optionally, you might define a path to HawkTracer's CMake module\n# CMake the path below should be a path to a directory where HawkTracerConfig.cmake is located, e.g.:\n# list(APPEND CMAKE_MODULE_PATH \"/usr/local/lib/cmake/HawkTracer\")\n\nfind_package(HawkTracer REQUIRED)\n\nadd_executable(your_project main.cc)\n\ntarget_link_libraries(your_project HawkTracer::hawktracer)\n\n```\n\n#### pkg-config\nHawkTracer 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:\n```bash\n$ g++ my_project.cpp $(pkg-config --cflags --libs hawktracer)\n```\n\n### Instrumenting code\n\n#### Initialize library\n\nBefore 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`.\nAdditionally, you need to specify an event listener. HawkTracer currently provides 2 listeners:\n* TCP listener, which streams events over the network\n* File dump listener, which saves events to a file.\n\nMoreover, HawkTracer allows to provide user-defined listeners.\nCode below presents example HawkTracer (un)initialization:\n```cpp\nint main(int argc, char** argv)\n{\n  ht_init(argc, argv); // initialize library\n  HT_Timeline* timeline = ht_global_timeline_get(); // timeline, where all events are posted. You can define your own timeline, or use global timeline\n  const size_t buffer_size = 4096; // size of internal listener's buffer\n  ht_file_dump_listener_register(ht_global_timeline_get(), \"hello-world-out.htdump\", 2048, NULL); // create listener and attach it to timeline\n\n  // your code goes here...\n\n  ht_deinit(); // uninitialize library\n\n  return 0;\n}\n\n```\nThe 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)).\n\n#### Instrumenting the code\nHawkTracer requires explicit code instrumentation. The library provides a few helper macros for reporting data to a timeline:\n```cpp\n// Pushes any type of event to a timeline\nHT_TIMELINE_PUSH_EVENT(TIMELINE, EVENT_TYPE, EVENT_PARAMETERS,...)\n\n// Reports a duration of specific block of code (available only for C++ or C GNU compiler)\nHT_TRACE(TIMELINE, LABEL)\n\n// The same as above, but automatically sets label to current function name\nHT_TRACE_FUNCTION(TIMELINE)\n```\nThere are few macros which report events to a global timeline, they're prefixed with `G_`:\n```cpp\nHT_G_TRACE(LABEL)\nHT_G_TRACE_OPT_STATIC(LABEL)\nHT_G_TRACE_OPT_DYNAMIC(LABEL)\nHT_G_TRACE_FUNCTION()\n```\nFor example, you can instrument following code:\n```cpp\nvoid foo()\n{\n  HT_G_TRACE_FUNCTION() // measure duration of foo function execution\n\n  for (int i = 0; i \u003c 100; i++)\n  {\n    HT_G_TRACE_OPT_STATIC(\"in-loop\") // measure duration of single loop iteration\n    bar();\n  }\n}\n```\n\n### Collect the data\n\nFor 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:\n```bash\nhawktracer-to-json --source file_name.htdump --output output_file.json\n```\n\n### Analyzing the data\n\n* Install google-chrome or chromium browser\n* Open the browser, and open [chrome://tracing/](chrome://tracing) webpage\n* Click load button and open file generated in the previous section\n* You should see a callstack with timing\n\n## Contributing\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.\n\n## Acknowledgment\n* Hat tip to anyone who's code was used\n* Inspiration\n* etc\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famzn%2Fhawktracer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famzn%2Fhawktracer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famzn%2Fhawktracer/lists"}