| Linux | Mac |
|---|---|
 |  |
Cpuusage is an instrumentation CPU profiler for Linux and macOS applications. It provides logging of standard POSIX function calls for any application, and logging of internal function calls for programs compiled with -finstrument-functions. The logging output format is a HTML-file generated using Chromium Catapult.
Tracing all POSIX function calls from a regular (non-instrumented) application:
$ cpuusage -v -o cutrace1.html -a ./ex001 cpuusage: https://github.com/d99kris/cpuusage cpuusage: initializing cpuusage: starting program ./ex001 cpuusage: processing output trace cpuusage: completed processing 96 samples $ xdg-open cutrace1.html Resulting visualization: 
Cpuusage is primarily developed and tested on Linux, but basic functionality should work in macOS as well. Current version has been tested on:
- macOS Sequoia 15.2
- Ubuntu 24.04 LTS
Limitation: On macOS this tool relies on code injection using DYLD_INSERT_LIBRARIES, which generally does not work with third-party applications in a standard system. Using it on (your own) applications built from source should work fine though.
Pre-requisites (Ubuntu):
sudo apt install git cmake build-essential python3-six Download the source code:
git clone https://github.com/d99kris/cpuusage && cd cpuusage Generate Makefile and build:
mkdir -p build && cd build && cmake .. && make -s Optionally install in system:
sudo make install General syntax:
cpuusage -a [OPTIONS] PROG [ARGS..] cpuusage -c [OPTIONS] PROG [ARGS..] cpuusage -f <FUNCTIONS> [OPTIONS] PROG [ARGS..] cpuusage -i <INCLUDES> [OPTIONS] PROG [ARGS..] cpuusage -p [OPTIONS] PROG [ARGS..] cpuusage -r JSONFILE [OPTIONS] cpuusage --help|-h cpuusage --version|-v Options:
-a trace all standard POSIX function calls -c trace internal function calls (requires PROG to be compiled with -finstrument-functions) -d debug mode, running program through debugger -e separate processes for child process trace -f <FUNCTIONS> trace specified POSIX functions -i <INCLUDES> trace functions in specified POSIX headers -p trace child process durations --help, -h display this help and exit --version, -v output version information and exit -j <PATH> write iterim JSON trace log to specified path -m <MINTIME> only log samples with minimum specified duration (in usec) currently only supported when tracing main-thread only. -n <SAMPLES> only log up to specified number of samples -o <PATH> write HTML report to specified path, rather than default ./cutrace-PID.html -r <JSONFILE> read JSON file and convert to HTML report -s start tracing with SIGUSR1 and stop with SIGUSR2, instead of trace from process start -u trace only main-thread -v verbose mode -y auto-open resulting html file PROG program to run and profile [ARGS] optional arguments to the program Tracing specified POSIX function calls from a regular (non-instrumented) application:
$ cpuusage -v -o cutrace2.html -f fopen,fwrite,fread,fclose ./ex001 cpuusage: https://github.com/d99kris/cpuusage cpuusage: initializing cpuusage: starting program ./ex001 cpuusage: processing output trace cpuusage: completed processing 36 samples $ xdg-open cutrace2.html Resulting visualization: 
Tracing internal function calls in an instrumented application:
$ cpuusage -v -o cutrace3.html -c ./ex002 cpuusage: https://github.com/d99kris/cpuusage cpuusage: initializing cpuusage: starting program ./ex002 cpuusage: processing output trace cpuusage: completed processing 8 samples $ xdg-open cutrace3.html Resulting visualization: 
Tracing internal function calls and all external POSIX function calls in an instrumented application:
$ cpuusage -v -o cutrace4.html -c -a ./ex002 cpuusage: https://github.com/d99kris/cpuusage cpuusage: initializing cpuusage: starting program ./ex002 cpuusage: processing output trace cpuusage: completed processing 104 samples $ xdg-open cutrace4.html Resulting visualization: 
Tracing process durations:
$ cpuusage -v -o cutrace5.html -p ./ex005.sh cpuusage: https://github.com/d99kris/cpuusage cpuusage: initializing cpuusage: starting program ./ex005.sh cpuusage: processing output trace cpuusage: completed processing 5 samples Resulting visualization: 
There are many CPU profilers available for Linux and macOS. Most of them are sample-based, and here is a list of some of them:
- Gperftools
- Gprof
- Instruments - Time Profiler
- Valgrind - Callgrind
Refer to ext/README.md for details on the external components used by cpuusage.
Cpuusage is distributed under the BSD 3-Clause license. See LICENSE file.
linux, macos, cpu usage, instrumented profiler, alternative to callgrind.