Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/d99kris/cpuusage
Instrumentation CPU profiler for Linux and macOS applications
https://github.com/d99kris/cpuusage
catapult cpu-profiling instrumentation linux macos profiling visualization
Last synced: about 2 months ago
JSON representation
Instrumentation CPU profiler for Linux and macOS applications
- Host: GitHub
- URL: https://github.com/d99kris/cpuusage
- Owner: d99kris
- License: bsd-3-clause
- Created: 2017-05-19T15:24:16.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-15T08:24:32.000Z (over 1 year ago)
- Last Synced: 2024-07-07T00:37:46.201Z (2 months ago)
- Topics: catapult, cpu-profiling, instrumentation, linux, macos, profiling, visualization
- Language: C
- Homepage:
- Size: 25.5 MB
- Stars: 19
- Watchers: 4
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-profiling - Cpuusage - Instrumentation CPU profiler for Linux and macOS applications. (1. System Overview)
README
Cpuusage
========
| **Linux** | **Mac** |
|-----------|---------|
| [](https://github.com/d99kris/cpuusage/actions?query=workflow%3ALinux) | [](https://github.com/d99kris/cpuusage/actions?query=workflow%3AmacOS) |
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](https://github.com/catapult-project/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 [OPTIONS] PROG [ARGS..]
cpuusage -i [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
trace specified POSIX functions
-i
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
write iterim JSON trace log to specified path
-m
only log samples with minimum specified duration (in usec)
currently only supported when tracing main-thread only.
-n
only log up to specified number of samples
-o
write HTML report to specified path, rather than default
./cutrace-PID.html
-r
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](/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.