{"id":16583568,"url":"https://github.com/sigill/instrmt","last_synced_at":"2026-02-19T11:02:42.629Z","repository":{"id":152621760,"uuid":"279111301","full_name":"Sigill/instrmt","owner":"Sigill","description":"Library providing a common API to various instrumentation tools.","archived":false,"fork":false,"pushed_at":"2025-03-23T22:31:09.000Z","size":346,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-09-15T09:39:50.779Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/Sigill.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"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,"zenodo":null}},"created_at":"2020-07-12T17:11:23.000Z","updated_at":"2025-03-23T22:31:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"b5892f7d-e79c-49e8-877a-54a1d4369bdf","html_url":"https://github.com/Sigill/instrmt","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Sigill/instrmt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sigill%2Finstrmt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sigill%2Finstrmt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sigill%2Finstrmt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sigill%2Finstrmt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sigill","download_url":"https://codeload.github.com/Sigill/instrmt/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sigill%2Finstrmt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29611002,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T10:52:55.328Z","status":"ssl_error","status_checked_at":"2026-02-19T10:52:26.323Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2024-10-11T22:36:00.584Z","updated_at":"2026-02-19T11:02:42.592Z","avatar_url":"https://github.com/Sigill.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Instrmt\n\n**Instrmt** is a C++ library that provides a common API to multiple instrumentation/tracing/telemetry ecosystems.\n\nIt especially supports with:\n\n- **itt**: Intel's [Instrumentation and Tracing Technology API (ITT API)](https://github.com/intel/ittapi).\\\n  Used by [VTune](https://www.intel.com/content/www/us/en/docs/vtune-profiler/user-guide/2025-0/instrumentation-and-tracing-technology-apis.html) and [Intel SEAPI](https://github.com/intel/IntelSEAPI) (discontinued).\n- **tracy**: [Tracy profiler](https://github.com/wolfpld/tracy).\n\n## Quick start\n\n### Build Instrmt\n\n```sh\n./scripts/fetch-ittapi.sh\n./scripts/fetch-tracy.sh\n\ncmake --preset=production\ncmake --build build/\n```\n\n### Instrument your project\n\n```cmake\n# CMakeLists.txt\ncmake_minimum_required(VERSION 3.14)\nproject(my_project)\n\nfind_package(Instrmt)\nadd_executable(app main.cpp)\ntarget_link_libraries(app PRIVATE instrmt)\n```\n\n```cpp\n// main.cpp\n#include \u003cinstrmt/instrmt.hxx\u003e\n\nint main(int, char**) {\n  INSTRMT_FUNCTION();\n  // ...\n  return 0;\n}\n```\n\n```sh\n$ cmake -S . -B build/ -DInstrmt_DIR=/path/to/instrmt/build\n$ cmake --build build/\n$ INSTRMT_ENGINE=/path/to/instrmt/build/libinstrmt-tty.so ./build/app\nmain                                     0.1 ms\n```\n\n## Instrumentation API\n\nAll of the public Instrmt C++ API is defined by macros in `instrmt/instrmt.hxx`.\n\n### Region markup\n\nA region define the start and end of a block of code (regions are similar to Intel's _Tasks_ or Tracy's _Zones_).\n\nThe following macros use RAII to bind the end of a region to the scope of the underlying variable.\n\n- `INSTRMT_FUNCTION()`: instrument the current scope, using the name of the function.\n- `INSTRMT_REGION(NAME)`: instrument the current scope, using a custom name.\n- `INSTRMT_NAMED_REGION(VAR, NAME)`: same as `INSTRMT_REGION`, but uses `VAR` as a prefix to prevent conflicts in the underlying variables.\n\nIf you cannot rely on RAII, use the following macros to manually markup the start and end of a region.\n\n- `INSTRMT_REGION_BEGIN(NAME)`, `INSTRMT_REGION_END()`\n- `INSTRMT_NAMED_REGION_BEGIN(VAR, NAME)`, `INSTRMT_NAMED_REGION_END(VAR)`\n\nFor performance reasons, `NAME` must be a string literal.\n\n### Messages\n\nMessages allow you to log arbitrary events to help you navigate through a program's trace.\n\nThe following macros are available:\n\n- `INSTRMT_LITERAL_MESSAGE(MSG)`, `INSTRMT_NAMED_LITERAL_MESSAGE(VAR, MSG)` for string literals.\n- `INSTRMT_MESSAGE(MSG)` for arbitrary strings.\n\n### Example\n\n```cpp\n// main.cpp\n#include \u003cinstrmt/instrmt.hxx\u003e\n\nvoid f() {\n  INSTRMT_FUNCTION();\n  // ...\n}\n\nint main(int, char**) {\n  f();\n  return 0;\n}\n```\n\n## Usage\n\n**Instrmt** gives access to the various ecosystems through _instrumentation engines_.\n\n### Dynamic wrapper\n\nThe `instrmt` library provides a mechanism to dynamically load an instrumentation engine at runtime.\n\nTo do that:\n\n- Include `instrmt/instrmt.hxx` and instrument your code.\n- Link against the `instrmt` library:\n\n  ```sh\n  g++ main.cpp -I/path/to/instrmt/include -L/path/to/instrmt/lib -linstrmt -ldl -o main\n  ```\n\n  Or using CMake:\n\n  ```cmake\n  find_package(Instrmt)\n  add_executable(main main.cpp)\n  target_link_libraries(main PRIVATE instrmt)\n  ```\n\n- When launching your application, specify the engine to load using the `INSTRMT_ENGINE` environment variable.\n\n  ```sh\n  $ ./main\n  # No instrumentation\n\n  $ INSTRMT_ENGINE=/path/to/instrmt/lib/libinstrmt-tty.so ./main\n  f                                0.0ms\n  ```\n\n### Static wrapper\n\nIf the dynamic wrapper has too much overhead, Instrmt can be used as a simple wrapper, providing just a common API (the macros) for other instrumentation libraries.\n\nWrappers for the _tty_, _itt_ \u0026 _tracy_ engines are provided.\n\nTo use a wrapper:\n\n- Include `instrmt/instrmt.hxx` and instrument your code.\n- Add the following define: `INSTRMT_CXX_WRAPPER=\\\"instrmt/xxx/xxx-wrapper.hxx\\\"` (with the double quotes).\n- Import the underlying library (your compiler needs to find its includes and link against it).\n\n#### TTY wrapper\n\n```sh\ng++ main.cpp -I/path/to/instrmt/include \\\n  -DINSTRMT_CXX_WRAPPER=\\\"instrmt/tty/tty-wrapper.hxx\\\" \\\n  -o main\n```\n\nOr using CMake:\n\n```cmake\nfind_package(Instrmt)\nadd_executable(main main.cpp)\ntarget_link_libraries(main instrmt-tty-wrapper)\n```\n\n#### ITT wrapper\n\n```sh\ng++ main.cpp -I/path/to/instrmt/include -I/path/to/ittnotify/include \\\n  -DINSTRMT_CXX_WRAPPER=\\\"instrmt/itt/itt-wrapper.hxx\\\" \\\n  -L/path/to/ittnotify/lib -littnotify -lpthread -ldl \\\n  -o main\n```\n\nOr using CMake:\n\n```cmake\nfind_package(Instrmt)\nadd_executable(main main.cpp)\ntarget_link_libraries(main instrmt-itt-wrapper)\n```\n\n#### Tracy wrapper\n\n```sh\ng++ main.cpp -I/path/to/instrmt/include -I/path/to/tracy/include \\\n  -DINSTRMT_CXX_WRAPPER=\\\"instrmt/tracy/tracy-wrapper.hxx\\\" \\\n  -DTRACY_ENABLE \\\n  -L/path/to/tracy/lib -lTracyClient -lpthread -ldl \\\n  -o main\n```\n\nOr using CMake:\n\n```cmake\nfind_package(Instrmt)\nadd_executable(main main.cpp)\ntarget_link_libraries(main instrmt-tracy-wrapper)\n```\n\n## Noop implementation\n\nWhen `INSTRMT_ENGINE` is not defined, every macro that instrument your code still has a small runtime overhead.\nYour application also needlessly links to (and has to be shipped with) the `instrmt` library.\n\nAll the macros can be turned noop, reducing the runtime overhead to zero, by adding the `INSTRMT_DISABLE` compile definition:\n\n```sh\ng++ main.cpp -I/path/to/instrmt/include -DINSTRMT_DISABLE -o main # No -linstrmt\n```\n\nUsing CMake, link to the `instrmt-noop` target instead:\n\n```cmake\ntarget_link_libraries(main PRIVATE instrmt-noop)\n```\n\n## Available engines\n\n### TTY\n\nAvailable options (not available in static wrapper mode at the moment):\n\n- `INSTRMT_TTY_OUT=stderr|stdout|\u003ca file\u003e`: Specify where to print the output.\\\n  When outputing to a file, if `%date%` is found in the filename, it will be replaced by the current date.\n- `INSTRMT_TTY_TRUNCATE_OUT`: Cause the output file to be truncated before writing to it.\n- `INSTRMT_TTY_COLOR=auto|yes|no`: Enable/disable colored output (default: auto).\n- `INSTRMT_TTY_FORMAT=text|csv`: Specify the output format (default: text).\n\n### ITT\n\nNote: Despite ITT API having an API for messages, VTune does not support them.\n\n### Tracy\n\n## License\n\nThis project is released under the terms of the MIT License. See the LICENSE.txt file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsigill%2Finstrmt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsigill%2Finstrmt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsigill%2Finstrmt/lists"}