https://github.com/plasma-umass/coz Skip to content Toggle navigation Sign in * Product + Actions Automate any workflow + Packages Host and manage packages + Security Find and fix vulnerabilities + Codespaces Instant dev environments + Copilot Write better code with AI + Code review Manage code changes + Issues Plan and track work + Discussions Collaborate outside of code Explore + All features + Documentation + GitHub Skills + Blog * Solutions For + Enterprise + Teams + Startups + Education By Solution + CI/CD & Automation + DevOps + DevSecOps Resources + Learning Pathways + White papers, Ebooks, Webinars + Customer Stories + Partners * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles Repositories + Topics + Trending + Collections * Pricing Search or jump to... Search code, repositories, users, issues, pull requests... Search [ ] Clear Search syntax tips Provide feedback We read every piece of feedback, and take your input very seriously. [ ] [ ] Include my email address so I can be contacted Cancel Submit feedback Saved searches Use saved searches to filter your results more quickly Name [ ] Query [ ] To see all available qualifiers, see our documentation. Cancel Create saved search Sign in Sign up You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert {{ message }} plasma-umass / coz Public * * Notifications * Fork 155 * Star 3.9k * Coz: Causal Profiling License View license 3.9k stars 155 forks Branches Tags Activity Star Notifications * Code * Issues 45 * Pull requests 8 * Discussions * Actions * Projects 0 * Wiki * Security * Insights Additional navigation options * Code * Issues * Pull requests * Discussions * Actions * Projects * Wiki * Security * Insights plasma-umass/coz This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. master BranchesTags Go to file Code Folders and files Last Last Name Name commit commit message date Latest commit History 546 Commits .github .github benchmarks benchmarks cmake cmake docs docs include include libcoz libcoz patches patches rust rust viewer viewer .gitignore .gitignore .travis.yml .travis.yml CMakeLists.txt CMakeLists.txt LICENSE.md LICENSE.md Makefile Makefile README.md README.md common.mk common.mk conanfile.txt conanfile.txt coz coz coz-profilerConfig.cmake.in coz-profilerConfig.cmake.in example-coz-output.png example-coz-output.png View all files Repository files navigation * README * License Coz: Finding Code that Counts with Causal Profiling by Charlie Curtsinger and Emery Berger Rust Crate downloads Coz is a profiler for native code (C/C++/Rust) that unlocks optimization opportunities missed by traditional profilers. Coz employs a novel technique called causal profiling that measures optimization potential. It predicts what the impact of optimizing code will have on overall throughput or latency. Profiles generated by Coz show the "bang for buck" of optimizing a line of code in an application. In the below profile, almost every effort to optimize the performance of this line of code directly leads to an increase in overall performance, making it an excellent candidate for optimization efforts. Example Coz profile Coz's measurement matches developers' assumptions about profilers: that optimizing highly-ranked code will have the greatest impact on performance. Causal profiling measures optimization potential for serial, parallel, and asynchronous programs without instrumentation of special handling for library calls and concurrency primitives. Instead, a causal profiler uses performance experiments to predict the effect of optimizations. This allows the profiler to establish causality: "optimizing function X will have effect Y," exactly the measurement developers had assumed they were getting all along. Full details of Coz are available in our paper, Coz: Finding Code that Counts with Causal Profiling (pdf), SOSP 2015, October 2015 (recipient of a Best Paper Award). Coz presentation at SOSP Installation On Debian and Ubuntu, you can install Coz via apt: sudo apt install coz-profiler An OpenSUSE package was prepared by user @zethra and is available at https://build.opensuse.org/package/show/home:zethra/coz-profiler. Coz should work on any modern Linux system (specifically, running version 2.6.32 or later, with support for the perf_event_open system call) with a Python 3.x interpreter. Libraries/Wrappers By default, Coz works for C, C++, and Rust programs. It has been ported or has wrappers for several other languages, listed below: Language Link Java JCoz: https://github.com/Decave/JCoz Go Cozgo: https://github.com/urjitbhatia/cozgo Swift Swift Coz: https://github.com/funcmike/swift-coz Building Coz From Source To build Coz from source, you will need: * A copy of the source code for this project * A compiler with C++0x support (clang++ or g++) * A Python interpreter (Python 3.x is required) * OPTIONAL: for building the profiler viewer, you need NodeJS and npm -- sudo apt-get install nodejs npm Once you have all dependencies in place, build Coz with CMake. On Debian-based distributions, the following commands should take care of the entire process: sudo apt-get update sudo apt-get install libdwarf-dev sudo apt-get install build-essential cmake docutils-common git python3 pkg-config git clone https://github.com/antoyo/libelfin && cd libelfin && make && sudo make install && cd .. git clone https://github.com/plasma-umass/coz && cd coz && cmake . && make && sudo make install && cd .. Next, you need to change the "perf_event_paranoia" level so Coz can run. sudo sh -c 'echo 1 >/proc/sys/kernel/perf_event_paranoid' Now you can test Coz. Build the benchmark suite and run one of the benchmarks (the SQLite3 benchmark takes a while to build). sudo apt-get install libbz2-dev libsqlite3-dev cd coz/benchmarks && cmake . && make && cd ../.. coz run --- ./coz/benchmarks/toy/toy Finally, use the Coz viewer to see the results. This command will open up a browser tab, from which you will need to load the file profile.coz. coz plot If you are on a remote system, you can open the Coz viewer in your browser: https://plasma-umass.github.io/coz and then load the file profile.coz, which you will have to transfer to your local machine. (You may need to move the "Minimum Points" slider on the left side to see the results.) Using Coz Using Coz requires a small amount of setup, but you can jump ahead to the section on the included sample applications in this repository if you want to try Coz right away. To run your program with Coz, you will need to build it with debug information (-g -gdwarf-3). You do not need to include debug symbols in the main executable: coz uses the same procedure as gdb to locate debug information for stripped binaries. Once you have your program built with debug information, you can run it with Coz using the command coz run {coz options} --- {program name and arguments}. But, to produce a useful profile you need to decide which part(s) of the application you want to speed up by specifying one or more progress points. Profiling Modes Coz departs from conventional profiling by making it possible to view the effect of optimizations on both throughput and latency. To profile throughput, you must specify a progress point. To profile latency, you must specify a pair of progress points. Throughput Profiling: Specifying Progress Points To profile throughput you must indicate a line in the code that corresponds to the end of a unit of work. For example, a progress point could be the point at which a transaction concludes, when a web page finishes rendering, or when a query completes. Coz then measures the rate of visits to each progress point to determine any potential optimization's effect on throughput. To place a progress point, include coz.h (under the include directory in this repository) and add the COZ_PROGRESS macro to at least one line you would like to execute more frequently. Don't forget to link your program with libdl: use the -ldl option. By default, Coz uses the source file and line number as the name for your progress points. If you use COZ_PROGRESS_NAMED("name for progress point") instead, you can provide an informative name for your progress points. This also allows you to mark multiple source locations that correspond to the same progress point. Latency Profiling: Specifying Progress Points To profile latency, you must place two progress points that correspond to the start and end of an event of interest, such as when a transaction begins and completes. Simply mark the beginning of a transaction with the COZ_BEGIN("transaction name") macro, and the end with the COZ_END("transaction name") macro. Unlike regular progress points, you always need to specify a name for your latency progress points. Don't forget to link your program with libdl: use the -ldl option. When coz tests a hypothetical optimization it will report the effect of that optimization on the average latency between these two points. Coz can track this information without any knowledge of individual transactions thanks to Little's Law. Specifying Progress Points on the Command Line Coz has command line options to specify progress points when profiling the application instead of modifying its source. This feature is currently disabled because it did not work particularly well. Adding support for better command line-specified progress points is planned in the near future. Processing Results To plot profile results, go to http://plasma-umass.github.io/coz/ and load your profile. This page also includes several sample profiles from PARSEC benchmarks. Sample Applications The benchmarks directory in this repository includes several small benchmarks with progress points added at appropriate locations. To build and run one of these benchmarks with coz, just browse to benchmarks/{bench name} and type cmake . && make. These programs may require several runs before coz has enough measurements to generate a useful profile. Once you have profiled these programs for several minutes, go to http://plasma-umass.github.io/coz/ to load and plot your profile. CMake When you install coz it installs a cmake config file. To add coz to a cmake project simply use the command find_package(coz-profiler). This will import a target for the library and includes called coz::coz and a target for the coz binary coz::profiler. For guidance on how to use these targets refer to the CMake documentation. Limitations Coz currently does not support interpreted or JIT-compiled languages such as Python, Ruby, or JavaScript. Interpreted languages will likely not be supported at any point, but support for JIT-compiled languages that produce debug information could be added in the future. License All source code is licensed under the BSD 2-clause license unless otherwise indicated. See LICENSE.md for details. Sample applications (in the benchmarks directory) include several Phoenix programs and pbzip2, which are licensed separately and included with this release for convenience. About Coz: Causal Profiling Topics performance-engineering profiler optimization performance-analysis causal-inference Resources Readme License View license Activity Custom properties Stars 3.9k stars Watchers 70 watching Forks 155 forks Report repository Releases 4 latest update for Debian Latest Aug 31, 2020 + 3 releases Sponsor this project Sponsor Learn more about GitHub Sponsors Packages 0 No packages published Used by 314 * @MayNc10 * @0xMRTT * @nicholas-miklaucic * @SodiumFRP * @SPIN-UMass * @endes0 * @j0ru * @proegssilb + 306 Contributors 35 * @ccurtsinger * @emeryberger * @petterreinholdtsen * @klimkin * @adklimki * @xd009642 * @fedorova * @flandr * @llvilanova * @drahnr * @camchenry * @zicklag * @jonhoo * @mmcco + 21 contributors Languages * C 96.7% * C++ 2.3% * JavaScript 0.4% * TypeScript 0.3% * CMake 0.1% * Rust 0.1% * Other 0.1% Footer (c) 2024 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact * Manage cookies * Do not share my personal information You can't perform that action at this time.