{"id":13418673,"url":"https://github.com/plasma-umass/coz","last_synced_at":"2026-02-15T17:44:01.901Z","repository":{"id":12039760,"uuid":"14625168","full_name":"plasma-umass/coz","owner":"plasma-umass","description":"Coz: Causal Profiling","archived":false,"fork":false,"pushed_at":"2026-02-13T14:46:44.000Z","size":10103,"stargazers_count":4448,"open_issues_count":46,"forks_count":167,"subscribers_count":67,"default_branch":"master","last_synced_at":"2026-02-13T23:21:08.135Z","etag":null,"topics":["causal-inference","optimization","performance-analysis","performance-engineering","profiler"],"latest_commit_sha":null,"homepage":"","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/plasma-umass.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["plasma-umass"]}},"created_at":"2013-11-22T17:57:13.000Z","updated_at":"2026-02-13T14:46:51.000Z","dependencies_parsed_at":"2023-10-01T23:33:27.553Z","dependency_job_id":"fb6ed870-5711-4185-a550-864155e7ce09","html_url":"https://github.com/plasma-umass/coz","commit_stats":{"total_commits":457,"total_committers":37,"mean_commits":12.35135135135135,"dds":"0.48577680525164113","last_synced_commit":"d0e7b8e375c241eb6e334b4e0e8e7cad1d2caa6c"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/plasma-umass/coz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plasma-umass%2Fcoz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plasma-umass%2Fcoz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plasma-umass%2Fcoz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plasma-umass%2Fcoz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plasma-umass","download_url":"https://codeload.github.com/plasma-umass/coz/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plasma-umass%2Fcoz/sbom","scorecard":{"id":737149,"data":{"date":"2025-08-11","repo":{"name":"github.com/plasma-umass/coz","commit":"7bb77a7d4e719150fa7c10acda39ce2b89b5df32"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4,"checks":[{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":4,"reason":"Found 8/18 approved changesets -- score normalized to 4","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":4,"reason":"3 commit(s) and 2 issue activity found in the last 90 days -- score normalized to 4","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"License","score":9,"reason":"license file detected","details":["Info: project has a license file: LICENSE.md:0","Warn: project license file does not contain an FSF or OSI license."],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 20 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-22T16:11:46.598Z","repository_id":12039760,"created_at":"2025-08-22T16:11:46.598Z","updated_at":"2025-08-22T16:11:46.598Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29486038,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T15:33:17.885Z","status":"ssl_error","status_checked_at":"2026-02-15T15:32:53.698Z","response_time":118,"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":["causal-inference","optimization","performance-analysis","performance-engineering","profiler"],"created_at":"2024-07-30T22:01:05.372Z","updated_at":"2026-02-15T17:44:01.895Z","avatar_url":"https://github.com/plasma-umass.png","language":"C","funding_links":["https://github.com/sponsors/plasma-umass"],"categories":["TODO scan for Android support in followings","Repositories","C","Profiling","Debugging \u0026 Profiling \u0026 Tracing","C++"],"sub_categories":["For C++/C"],"readme":"# Coz: Finding Code that Counts with Causal Profiling\n\nby [Charlie Curtsinger](https://curtsinger.cs.grinnell.edu/) and [Emery Berger](https://emeryberger.com)\n\n[![Rust Crate downloads](https://img.shields.io/crates/d/coz?logo=rust\u0026link=https%3A%2F%2Fcrates.io%2Fcrates%2Fcoz)](https://crates.io/crates/coz)\n\nCoz is a profiler for native code (C/C++/Rust) that unlocks\noptimization opportunities missed by traditional profilers. Coz\nemploys a novel technique called *causal profiling* that measures\noptimization potential. It predicts what the impact of optimizing code\nwill have on overall throughput or latency.\n\nProfiles generated by Coz show the \"bang for buck\" of optimizing a\nline of code in an application. In the below profile, almost every\neffort to optimize the performance of this line of code directly leads\nto an increase in overall performance, making it an excellent\ncandidate for optimization efforts.\n\n![Example Coz profile](https://github.com/plasma-umass/coz/blob/master/example-coz-output.png)\n\nCoz'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.\n\nFull details of Coz are available in our paper, [Coz: Finding Code\nthat Counts with Causal Profiling\n(pdf)](http://arxiv.org/pdf/1608.03676v1.pdf), SOSP 2015, October 2015\n(recipient of a Best Paper Award).\n\n[![Coz presentation at SOSP](http://img.youtube.com/vi/jE0V-p1odPg/0.jpg)](http://www.youtube.com/watch?v=jE0V-p1odPg\u0026t=0m28s \"Coz presentation at SOSP\")\n\n## Installation\n\n### Pre-built Packages (Recommended)\n\nDownload the latest release for your platform from the [GitHub Releases page](https://github.com/plasma-umass/coz/releases).\n\n**Debian/Ubuntu (`.deb`):**\n```shell\n# Download the .deb for your architecture (amd64 or arm64)\nsudo dpkg -i coz_VERSION_amd64.deb\n```\n\n**Fedora/RHEL/CentOS (`.rpm`):**\n```shell\n# Download the .rpm for your architecture (x86_64 or aarch64)\nsudo rpm -i coz-VERSION-1.x86_64.rpm\n```\n\n**Generic Linux (tarball):**\n```shell\ntar xzf coz-VERSION-linux-x86_64.tar.gz\ncd coz-VERSION-linux-x86_64\nsudo ./install.sh        # Installs to /usr/local by default\nsudo ldconfig\n```\n\n### Requirements\n\nCoz works on Linux systems (running version 2.6.32 or later, with support\nfor the `perf_event_open` system call) and macOS (using Apple's kperf framework).\nBoth platforms require a Python 3.x interpreter.\n\n**macOS Note**: The macOS port uses Apple's private kperf framework for sampling.\nThis requires either running with elevated privileges or adjusting System Integrity\nProtection settings. The kperf API is undocumented and may change in future macOS versions.\n\n## Libraries/Wrappers\n\nBy default, Coz works for C, C++, and Rust programs. It has been ported or\nhas wrappers for several other languages, listed below:\n\n| Language      | Link |\n| ----------- | -----------  \n| Java   | JCoz: https://github.com/Decave/JCoz|\n| Go     | Cozgo: https://github.com/urjitbhatia/cozgo|\n| Swift  | Swift Coz: https://github.com/funcmike/swift-coz |\n\n## Building Coz From Source\n\n### Install build prerequisites\n\nOn Debian/Ubuntu:\n\n```shell\nsudo apt-get install -y build-essential cmake pkg-config\n```\n\nlibelfin is fetched automatically during the build, so no additional dependencies are required.\n\n### Configure and build\n\nUse the standard out-of-source workflow (shown with `build/`, but any directory works):\n\n```shell\ncmake -S . -B build          # Configure (defaults to Release with debug info)\ncmake --build build -j       # Build libcoz and the CLI\nsudo cmake --install build   # Install to /usr/local (or CMAKE_INSTALL_PREFIX)\nsudo ldconfig                # Update shared library cache\n```\n\nBefore running Coz on Linux, relax `perf_event_paranoid` so sampling works:\n\n```shell\nsudo sh -c 'echo 1 \u003e/proc/sys/kernel/perf_event_paranoid'\n```\n\n### Building the Benchmarks\n\nThe benchmark suite is off by default because it pulls in extra dependencies. Enable it when configuring:\n\n```shell\ncmake -S . -B build-bench -DBUILD_BENCHMARKS=ON\ncmake --build build-bench -j\n```\n\nWhen `BUILD_BENCHMARKS` is set, CMake automatically switches the build type to `RelWithDebInfo` (or keeps `Debug`) so DWARF line tables are available. Benchmark binaries live under `build-bench/benchmarks/\u003cname\u003e/`.\n\nA number of the benchmarks are from the Phoenix benchmark suite, and several require data files. These are available for download via links in the README from [the Phoenix repository](https://github.com/kozyraki/phoenix).\n\n### Viewer\n\nAfter profiling, run `coz plot` to automatically open your results in the browser. To view a specific profile, use `coz plot -i /path/to/profile.coz`.\n\nYou may need to adjust the \"Minimum Points\" slider to see results if the profile has limited data.\n\n#### AI-Powered Optimization Suggestions\n\nThe viewer includes an AI assistant that analyzes causal profiling results and suggests concrete optimizations. Click the magic wand icon on any plot to get context-aware suggestions based on the profiling data and source code.\n\nSupported LLM providers:\n- **Anthropic** (Claude) — set `ANTHROPIC_API_KEY`\n- **OpenAI** (GPT-4o, o3, etc.) — set `OPENAI_API_KEY`\n- **Amazon Bedrock** — set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`\n- **Ollama** — local models, no API key required\n\nThe viewer dynamically fetches available models from each provider and caches them locally. Provider settings, API keys, and model selections persist across sessions via cookies.\n\n## Using Coz\nUsing Coz requires a small amount of setup, but you can jump ahead to the section on the included [sample applications](#sample-applications) in this repository if you want to try Coz right away.\n\nTo run your program with Coz, you will need to build it with debug information (`-g`). Coz now supports modern DWARF versions (including DWARF 5), so you can use your compiler's default debug format. 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.\n\nOnce 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.\n\n### Profiling Modes\nCoz 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.\n\n#### Throughput Profiling: Specifying Progress Points\nTo 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.\n\nTo 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.\n\nBy 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.\n\n#### Latency Profiling: Specifying Progress Points\nTo 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.\n\nWhen 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](https://en.wikipedia.org/wiki/Little%27s_law).\n\n### Specifying Progress Points on the Command Line\nCoz 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.\n\n## Processing Results\nRun `coz plot` to view your profile in the browser. Use `coz plot --text` for terminal output, or `coz plot --text --verbose` for detailed data points.\n\n## Sample Applications\nThe `benchmarks/` directory includes several small programs with progress points already wired up. Once you configure with `-DBUILD_BENCHMARKS=ON` (see above), you can run them straight from the build tree:\n\n```shell\n./build-bench/benchmarks/toy/toy\ncoz run --- ./build-bench/benchmarks/toy/toy\n```\n\nThese programs may need several runs before Coz accumulates enough samples to emit a useful profile. Run `coz plot` to view the results.\n\n## CMake\nWhen 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.\n\n## Limitations\nCoz 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.\n\n## License\nAll source code is licensed under the BSD 2-clause license unless otherwise indicated. See LICENSE.md for details.\n\nSample applications (in the `benchmarks` directory) include several [Phoenix](https://github.com/kozyraki/phoenix) programs and [pbzip2](http://compression.ca/pbzip2/), which are licensed separately and included with this release for convenience.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplasma-umass%2Fcoz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplasma-umass%2Fcoz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplasma-umass%2Fcoz/lists"}