Coz: Finding Code that Counts with Causal Profiling
by Charlie Curtsinger and Emery Berger
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.
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).
Installation
Pre-built Packages (Recommended)
Download the latest release for your platform from the GitHub Releases page.
Debian/Ubuntu (.deb):
# Download the .deb for your architecture (amd64 or arm64)
sudo dpkg -i coz_VERSION_amd64.deb
Fedora/RHEL/CentOS (.rpm):
# Download the .rpm for your architecture (x86_64 or aarch64)
sudo rpm -i coz-VERSION-1.x86_64.rpm
Generic Linux (tarball):
tar xzf coz-VERSION-linux-x86_64.tar.gz
cd coz-VERSION-linux-x86_64
sudo ./install.sh # Installs to /usr/local by default
sudo ldconfig
Requirements
Coz works on Linux systems (running version 2.6.32 or later, with support
for the perf_event_open system call) and macOS (using Apple's kperf framework).
Both platforms require a Python 3.x interpreter.
macOS Note: The macOS port uses Apple's private kperf framework for sampling.
This requires either running with elevated privileges or adjusting System Integrity
Protection settings. The kperf API is undocumented and may change in future macOS versions.
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:
Building Coz From Source
Install build prerequisites
On Debian/Ubuntu:
sudo apt-get install -y build-essential cmake pkg-config
libelfin is fetched automatically during the build, so no additional dependencies are required.
Configure and build
Use the standard out-of-source workflow (shown with build/, but any directory works):
cmake -S . -B build # Configure (defaults to Release with debug info)
cmake --build build -j # Build libcoz and the CLI
sudo cmake --install build # Install to /usr/local (or CMAKE_INSTALL_PREFIX)
sudo ldconfig # Update shared library cache
Before running Coz on Linux, relax perf_event_paranoid so sampling works:
sudo sh -c 'echo 1 >/proc/sys/kernel/perf_event_paranoid'
Building the Benchmarks
The benchmark suite is off by default because it pulls in extra dependencies. Enable it when configuring:
cmake -S . -B build-bench -DBUILD_BENCHMARKS=ON
cmake --build build-bench -j
When 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/<name>/.
A 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.
Viewer
After 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.
You may need to adjust the "Minimum Points" slider to see results if the profile has limited data.
AI-Powered Optimization Suggestions
The 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.
Supported LLM providers:
- Anthropic (Claude) — set
ANTHROPIC_API_KEY
- OpenAI (GPT-4o, o3, etc.) — set
OPENAI_API_KEY
- Amazon Bedrock — set
AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
- Ollama — local models, no API key required
The viewer dynamically fetches available models from each provider and caches them locally. Provider settings, API keys, and model selections persist across sessions via cookies.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
