README.md

Cpuusage

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.

Example Usage

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:

Supported Platforms

Cpuusage is primarily developed and tested on Linux, but basic functionality should work in macOS as well. Current version has been tested on:

• macOS Big Sur 11.0
• Ubuntu 20.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.

Installation

Pre-requisites (Ubuntu):

sudo apt install git cmake build-essential python-lxml

Pre-requisites (Python):

pip3 install -U 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

Usage

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

More Examples

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:

Alternatives

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

Technical Details

Refer to ext/README.md for details on the external components used by cpuusage.

License

Cpuusage is distributed under the BSD 3-Clause license. See LICENSE file.

Keywords

linux, macos, cpu usage, instrumented profiler, alternative to callgrind.