{"id":29028066,"url":"https://github.com/fmoessbauer/drace","last_synced_at":"2026-03-11T07:33:31.081Z","repository":{"id":55112611,"uuid":"139347462","full_name":"fmoessbauer/drace","owner":"fmoessbauer","description":"Data-race detector for windows applications build on top of DynamoRIO. Moved to","archived":false,"fork":false,"pushed_at":"2021-01-09T13:15:25.000Z","size":1659,"stargazers_count":4,"open_issues_count":0,"forks_count":8,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-26T07:05:28.583Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/siemens/drace","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fmoessbauer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-07-01T17:17:14.000Z","updated_at":"2022-01-06T18:53:28.000Z","dependencies_parsed_at":"2022-08-14T12:20:44.950Z","dependency_job_id":null,"html_url":"https://github.com/fmoessbauer/drace","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/fmoessbauer/drace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmoessbauer%2Fdrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmoessbauer%2Fdrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmoessbauer%2Fdrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmoessbauer%2Fdrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fmoessbauer","download_url":"https://codeload.github.com/fmoessbauer/drace/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmoessbauer%2Fdrace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30374349,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T06:09:32.197Z","status":"ssl_error","status_checked_at":"2026-03-11T06:09:17.086Z","response_time":84,"last_error":"SSL_read: 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":"2025-06-26T07:05:27.652Z","updated_at":"2026-03-11T07:33:31.061Z","avatar_url":"https://github.com/fmoessbauer.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DRace\n\n[![reuse compliant](https://reuse.software/badge/reuse-compliant.svg)](https://reuse.software/)\n\nDRace is a data-race detector for windows applications which uses DynamoRIO\nto dynamically instrument a binary at runtime.\nIt does not require any preparations like instrumentation of the binary to check.\nWhile the detector should work with all binaries that use the POSIX synchronization API,\nwe focus on applications written in C and C++.\nExperimental support for hybrid applications containing native and Dotnet CoreCLR parts\nis implemented as well.\n\nFor best results, we recommend to provide debug symbols of the\napplication under test along with the binary.\nWithout this information, callstacks cannot be fully symbolized (exported functions only)\nand user-level synchronization cannot be detected.\n\n## Dependencies\n\n- CMake \u003e 3.8\n- [DynamoRIO](https://github.com/DynamoRIO/dynamorio) 7.0.x (use weekly releases)\n- C++11 / C99 Compiler\n\nFor detailed information on all dependencies, see `DEPENDENCIES.md`.\n\n### External Libraries\n\n#### DRace\n\n**Mandatory:**\n\n- [jtilly/inih](https://github.com/jtilly/inih)\n- [HowardHinnant/date](https://github.com/HowardHinnant/date)\n- [muellan/clipp](https://github.com/muellan/clipp)\n- LLVM-Tsan (a customized version is included in binary format)\n\n**Optional:**\n\n- [leethomason/tinyxml2](https://github.com/leethomason/tinyxml2)\n- [google/googletest](https://github.com/google/googletest)\n- [google/benchmark](https://github.com/google/benchmark)\n\n#### Managed Symbol Resolver (MSR)\n\n**Mandatory:**\n\n- [gabime/spdlog](https://github.com/gabime/spdlog)\n- [greq7mdp/sparsepp](https://github.com/greg7mdp/sparsepp)\n\n## Using the DRace Race Detector\n\n**Run the detector as follows**\n\n```bash\ndrrun.exe -no_follow_children -c drace-client.dll \u003cdetector parameter\u003e -- application.exe \u003capp parameter\u003e\n# see limitations for -no_follow_children option\n```\n\n**Command Line Options**\n\n```\nSYNOPSIS\n        drace-client.dll [-c \u003cconfig\u003e] [-s \u003csample-rate\u003e] [-i \u003cinstr-rate\u003e] [--lossy\n                         [--lossy-flush]] [--excl-traces] [--excl-stack] [--excl-master] [--stacksz\n                         \u003cstacksz\u003e] [--delay-syms] [--sync-mode] [--fast-mode] [--xml-file\n                         \u003cfilename\u003e] [--out-file \u003cfilename\u003e] [--logfile \u003cfilename\u003e] [--extctrl]\n                         [--brkonrace] [--version] [-h] [--heap-only]\n\nOPTIONS\n        DRace Options\n            -c, --config \u003cconfig\u003e\n                    config file (default: drace.ini)\n\n            sampling options\n                -s, --sample-rate \u003csample-rate\u003e\n                    sample each nth instruction (default: no sampling)\n\n                -i, --instr-rate \u003cinstr-rate\u003e\n                    instrument each nth instruction (default: no sampling)\n\n            analysis scope\n                --lossy\n                    dynamically exclude fragments using lossy counting\n\n                --lossy-flush\n                    de-instrument flushed segments (only with --lossy)\n\n                --excl-traces\n                    exclude dynamorio traces\n\n                --excl-stack\n                    exclude stack accesses\n\n                --excl-master\n                    exclude first thread\n\n            --stacksz \u003cstacksz\u003e\n                    size of callstack used for race-detection (must be in [1,16], default: 10)\n\n            --delay-syms\n                    perform symbol lookup after application shutdown\n\n            --sync-mode\n                    flush all buffers on a sync event (instead of participating only)\n\n            --fast-mode\n                    DEPRECATED: inverse of sync-mode\n\n            data race reporting\n                --xml-file, -x \u003cfilename\u003e\n                    log races in valkyries xml format in this file\n\n                --out-file, -o \u003cfilename\u003e\n                    log races in human readable format in this file\n\n            --logfile, -l \u003cfilename\u003e\n                    write all logs to this file (can be null, stdout, stderr, or filename)\n\n            --extctrl\n                    use second process for symbol lookup and state-controlling (required for Dotnet)\n\n            --brkonrace\n                    abort execution after first race is found (for testing purpose only)\n\n            --version\n                    display version information\n\n            -h, --usage\n                    display help\n\n        Detector (TSAN) Options\n            --heap-only\n                    only analyze heap memory\n\n```\n\n### Externally Controlling DRace\n\nDRace can be externally controlled from a controller (`msr.exe`) running in a second process.\nTo set the detector state during runtime, the following keys (committed using `enter`) are available:\n\n```\ne        enable detector on all threads\nd        disable detector on all threads\ns \u003crate\u003e set sampling rate to 1/x (similar to `-s` in DRace)\n```\n\n### Symbol Resolving\n\nDRace requires symbol information for wrapping functions and to resolve stack traces.\nFor the main functionality of C and C++ only applications, export information is sufficient.\nHowever for additional and more precise race-detection (e.g. C++11, QT), debug information is necessary.\n\nThe application searches for this information in the path of the module and in `_NT_SYMBOL_PATH`.\nHowever, only local symbols are searched (non `SRV` parts).\n\nIf symbols for system libraries are necessary (e.g. for Dotnet), they have to be downloaded from a symbol server.\nThereto it is useful to set the variable as follows:\n\n```\nset _NT_SYMBOL_PATH=\"c:\\\\symbolcache\\\\;SRV*c:\\\\symbolcache\\\\*https://msdl.microsoft.com/download/symbols\"\n```\n\n### Dotnet\n\nFor .Net managed code, a second process (MSR) is needed for symbol resolution.\nThe MSR is started as follows:\n\n```\nManagedResolver\\msr.exe [-v for verbose]\n```\n\nAfter it is started, DRace connects to MSR using shared memory.\nThe MSR then tries to locate the correct [DAC](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/dac-notes.md)\nDLL to resolve managed program counters and symbols.\n\nThe output (logs) of the MSR are just for debugging reasons.\nThe resolved symbols are passed back to drace and merged with the non-managed ones.\n\n### Custom Annotations\n\nCustom synchonisation logic is supported by annotating the corresponding code sections.\nThereto we provide a header with macros in `drace-client/include/annotations/drace_annotation.h`.\nTo enable these macros, define `DRACE_ANNOTATION` prior to including the header.\n\nA example on how to use the annotations is provided in `test/mini-apps/annotations/`.\n\n## Testing with GoogleTest\n\nBoth the detector and a fully integrated DR-Client can be tested using the following command:\n\n```\n# Detector Tests\n./test/drace-client-Tests.exe --dr \u003cpath-to-drrun.exe\u003e --gtest_filter=\"Detector*\"\n# Integration Tests\n./test/drace-client-Tests.exe --dr \u003cpath-to-drrun.exe\u003e --gtest_filter=\"Dr*\"\n```\n\n**Note:** Before pushing a commit, please run the integration tests.\nLater on, bugs are very tricky to find. \n\n## Limitations\n\n- CSharp applications do not run on Windows 10 [#3046](https://github.com/DynamoRIO/dynamorio/issues/3046)\n- TSAN can only be started once, as the cleanup is not fully working\n- `no_follow_children`: Due to the TSAN limitation, drace can only analyze a single process. This process is the initially started one.\n- If using the SparsePP hashmap, the application might crash if a reallocation occurs which is not detected by DR correctly.\n\n## Build\n\nDRace is build using CMake. The only external dependency is DynamoRIO.\nFor best compability with Windows 10, use the latest available weekly build.\nThe path to your DynamoRIO installation has to be set using `-DDynamoRIO_DIR`.\n\nA sample VisualStudio `CMakeSettings.json` is given here:\n\n```\n{\n  \"name\": \"x64-Release-TSAN\",\n  \"generator\": \"Ninja\",\n  \"configurationType\": \"RelWithDebInfo\",\n  \"inheritEnvironments\": [ \"msvc_x64_x64\" ],\n  \"buildRoot\": \"${env.USERPROFILE}\\\\CMakeBuilds\\\\${workspaceHash}\\\\build\\\\${name}\",\n  \"installRoot\": \"${env.USERPROFILE}\\\\CMakeBuilds\\\\${workspaceHash}\\\\install\\\\${name}\",\n  \"cmakeCommandArgs\": \"-DDRACE_XML_EXPORTER=1 -DDRACE_ENABLE_TESTING=1 -DDRACE_ENABLE_BENCH=1 -DDynamoRIO_DIR=\u003cPATH-TO-DYNAMORIO\u003e/cmake -DDRACE_DETECTOR=tsan\",\n  \"buildCommandArgs\": \"-v\",\n  \"ctestCommandArgs\": \"\"\n}\n```\n\nTo clone all submodules of this repository, issue the following command inside the drace directory:\n\n```\ngit submodule update --recursive\n```\n\n### Documentation\n\nA doxygen documentation can be generated by building the `doc` target.\n\n### Available Detectors\n\nDRace is shipped with the following detector backends:\n\n- tsan (internal ThreadSanitizer)\n- extsan (external ThreadSanitizer, WIP)\n- dummy (no detection at all)\n\nTo select which detector is build, set the `-DDRACE_DETECTOR=\u003cvalue\u003e` CMake flag.\n\n**tsan**\n\nThe detector is run along with the application. No further threads are started.\n\n**extsan**\n\nDRace sends all events (memory-accesses, sync events, ...) to a different process (MSR) using shared memory and fifo queues.\nThe MSR process then passes the events to the ThreadSanitizer. For communication and analysis, an arbitrary number of queues can be used.\nEach queue is then processed and analyzed by it's own thread.\n\n*Note*: This is work-in-progress and is there for evaluation of this concept. On systems with only a few cores, the performance is poor.\n\n**dummy**\n\nThis detector does not detect any races. It is there to evaluate the overhead of the other detectors vs the instrumentation overhead.\n\n## Licensing\n\nDRace is primarily licensed under the terms of the MIT license.\n\nEach of its source code files contains a license declaration in its header. Whenever a file is provided under an additional or different license than MIT, this is stated in the file header.\nAny file that may lack such a header has to be considered licensed under MIT (default license).\n\nIf two licenses are specified in a file header, you are free to pick the one that suits best your particular use case.\nYou can also continue to use the file under the dual license.\nWhen choosing only one, remove the reference to the other from the file header.\n\n### External Ressources\n\nMost external ressources are located in the `vendor` directory.\nFor licensing information regarding these components, we refer to the information bundled with the individual ressource.\n\n### License Header Format\n\nWe use the [REUSE](https://reuse.software/practices/) format for license and copyright information.\n\n```\n/*\n * DRace, a dynamic data race detector\n *\n * Copyright \u003cYEAR\u003e \u003cCOPYRIGHT HOLDER\u003e\n *\n * SPDX-License-Identifier: MIT \n */\n```\n\n## Citing DRace\n\nA publicly available fulltext of the master's thesis can be found here: [High Performance Dynamic Threading Analysis for Hybrid Applications](https://epub.ub.uni-muenchen.de/60621/)\n\nTo cite DRace, please reference:\n\n```\nF. Mößbauer. \"High Performance Dynamic Threading Analysis for Hybrid Applications\", Master Thesis, Faculty of Mathematics, Computer Science and Statistics, Ludwig-Maximilians-Universität München (2019).\n```\n\n**BibTex**\n```\n@misc{moes19,\n           title = {High Performance Dynamic Threading Analysis for Hybrid Applications},\n         keyword = {Concurrency Bugs; Race Condition; Program Analysis; Binary Instrumentation; Sampling; Managed Applications},\n        abstract = {Verifying the correctness of multithreaded programs is a challenging task due to errors that occur sporadically. Testing, the most important verification method for decades, has proven to be ineffective in this context. On the other hand, data race detectors are very successful in finding concurrency bugs that occur due to missing synchronization. However, those tools introduce a huge runtime overhead and therefore are not applicable to the analysis of real-time applications. Additionally, hybrid binaries consisting of Dotnet and native components are beyond the scope of many data race detectors.\nIn this thesis, we present a novel approach for a dynamic low-overhead data race detector. We contribute a set of fine-grained tuning techniques based on sampling and scoping. These are evaluated on real-world applications, demonstrating that the runtime overhead is reduced while still maintaining a good detection accuracy. Further, we present a proof of concept for hybrid applications and show that data races in managed Dotnet code are detectable by analyzing the \napplication on the binary layer. The approaches presented in this thesis are implemented in the open-source tool DRace.},\n            year = {2019},\n          author = {Felix M\\\"o\\ssbauer},\n             url = {http://nbn-resolving.de/urn/resolver.pl?urn=nbn:de:bvb:19-epub-60621-8}\n}\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffmoessbauer%2Fdrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffmoessbauer%2Fdrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffmoessbauer%2Fdrace/lists"}