{"id":13696661,"url":"https://github.com/d99kris/cpuusage","last_synced_at":"2025-05-16T14:33:21.982Z","repository":{"id":50645468,"uuid":"91819458","full_name":"d99kris/cpuusage","owner":"d99kris","description":"Instrumentation CPU profiler for Linux and macOS applications","archived":false,"fork":false,"pushed_at":"2023-01-15T08:24:32.000Z","size":26779,"stargazers_count":19,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-13T00:32:59.237Z","etag":null,"topics":["catapult","cpu-profiling","instrumentation","linux","macos","profiling","visualization"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/d99kris.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-19T15:24:16.000Z","updated_at":"2024-01-24T08:35:46.000Z","dependencies_parsed_at":"2023-02-09T21:31:05.781Z","dependency_job_id":null,"html_url":"https://github.com/d99kris/cpuusage","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d99kris%2Fcpuusage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d99kris%2Fcpuusage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d99kris%2Fcpuusage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d99kris%2Fcpuusage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/d99kris","download_url":"https://codeload.github.com/d99kris/cpuusage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225433465,"owners_count":17473599,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["catapult","cpu-profiling","instrumentation","linux","macos","profiling","visualization"],"created_at":"2024-08-02T18:00:44.423Z","updated_at":"2025-05-16T14:33:21.976Z","avatar_url":"https://github.com/d99kris.png","language":"C","readme":"Cpuusage\n========\n\n| **Linux** | **Mac** |\n|-----------|---------|\n| [![Linux](https://github.com/d99kris/cpuusage/workflows/Linux/badge.svg)](https://github.com/d99kris/cpuusage/actions?query=workflow%3ALinux) | [![macOS](https://github.com/d99kris/cpuusage/workflows/macOS/badge.svg)](https://github.com/d99kris/cpuusage/actions?query=workflow%3AmacOS) |\n\nCpuusage is an instrumentation CPU profiler for Linux and macOS applications.\nIt provides logging of standard POSIX function calls for any application, and logging of\ninternal function calls for programs compiled with -finstrument-functions.\nThe logging output format is a HTML-file generated using\n[Chromium Catapult](https://github.com/catapult-project/catapult).\n\nExample Usage\n=============\nTracing all POSIX function calls from a regular (non-instrumented) application:\n\n    $ cpuusage -v -o cutrace1.html -a ./ex001\n    cpuusage: https://github.com/d99kris/cpuusage\n    cpuusage: initializing\n    cpuusage: starting program ./ex001\n    cpuusage: processing output trace\n    cpuusage: completed processing 96 samples\n    $ xdg-open cutrace1.html\n\nResulting visualization:\n![culog1 screenshot](/doc/culog1.png)\n\nSupported Platforms\n===================\nCpuusage is primarily developed and tested on Linux, but basic functionality\nshould work in macOS as well. Current version has been tested on:\n- macOS Sequoia 15.2\n- Ubuntu 24.04 LTS\n\nLimitation: On macOS this tool relies on code injection using\nDYLD_INSERT_LIBRARIES, which generally does not work with third-party\napplications in a standard system. Using it on (your own) applications built\nfrom source should work fine though.\n\nInstallation\n============\nPre-requisites (Ubuntu):\n\n    sudo apt install git cmake build-essential python3-six\n\nDownload the source code:\n\n    git clone https://github.com/d99kris/cpuusage \u0026\u0026 cd cpuusage\n\nGenerate Makefile and build:\n\n    mkdir -p build \u0026\u0026 cd build \u0026\u0026 cmake .. \u0026\u0026 make -s\n\nOptionally install in system:\n\n    sudo make install\n\nUsage\n=====\n\nGeneral syntax:\n\n    cpuusage -a [OPTIONS] PROG [ARGS..]\n    cpuusage -c [OPTIONS] PROG [ARGS..]\n    cpuusage -f \u003cFUNCTIONS\u003e [OPTIONS] PROG [ARGS..]\n    cpuusage -i \u003cINCLUDES\u003e [OPTIONS] PROG [ARGS..]\n    cpuusage -p [OPTIONS] PROG [ARGS..]\n    cpuusage -r JSONFILE [OPTIONS]\n    cpuusage --help|-h\n    cpuusage --version|-v\n\nOptions:\n\n    -a     trace all standard POSIX function calls\n\n    -c     trace internal function calls (requires PROG to be compiled with\n           -finstrument-functions)\n\n    -d     debug mode, running program through debugger\n\n    -e     separate processes for child process trace\n\n    -f \u003cFUNCTIONS\u003e\n           trace specified POSIX functions\n\n    -i \u003cINCLUDES\u003e\n           trace functions in specified POSIX headers\n\n    -p     trace child process durations\n\n    --help, -h\n           display this help and exit\n\n    --version, -v\n           output version information and exit\n\n    -j \u003cPATH\u003e\n           write iterim JSON trace log to specified path\n\n    -m \u003cMINTIME\u003e\n           only log samples with minimum specified duration (in usec)\n           currently only supported when tracing main-thread only.\n\n    -n \u003cSAMPLES\u003e\n           only log up to specified number of samples\n\n    -o \u003cPATH\u003e\n           write  HTML  report  to  specified  path,  rather  than  default\n           ./cutrace-PID.html\n\n    -r \u003cJSONFILE\u003e\n           read JSON file and convert to HTML report\n\n    -s     start tracing with SIGUSR1 and stop with SIGUSR2, instead of\n           trace from process start\n\n    -u     trace only main-thread\n\n    -v     verbose mode\n\n    -y     auto-open resulting html file\n\n    PROG   program to run and profile\n\n    [ARGS] optional arguments to the program\n\nMore Examples\n=============\n**Tracing specified POSIX function calls from a regular (non-instrumented) application:**\n\n    $ cpuusage -v -o cutrace2.html -f fopen,fwrite,fread,fclose ./ex001\n    cpuusage: https://github.com/d99kris/cpuusage\n    cpuusage: initializing\n    cpuusage: starting program ./ex001\n    cpuusage: processing output trace\n    cpuusage: completed processing 36 samples\n    $ xdg-open cutrace2.html\n\nResulting visualization:\n![culog2 screenshot](/doc/culog2.png)\n\n**Tracing internal function calls in an instrumented application:**\n\n    $ cpuusage -v -o cutrace3.html -c ./ex002\n    cpuusage: https://github.com/d99kris/cpuusage\n    cpuusage: initializing\n    cpuusage: starting program ./ex002\n    cpuusage: processing output trace\n    cpuusage: completed processing 8 samples\n    $ xdg-open cutrace3.html\n\nResulting visualization:\n![culog3 screenshot](/doc/culog3.png)\n\n**Tracing internal function calls and all external POSIX function calls in an instrumented application:**\n\n    $ cpuusage -v -o cutrace4.html -c -a ./ex002\n    cpuusage: https://github.com/d99kris/cpuusage\n    cpuusage: initializing\n    cpuusage: starting program ./ex002\n    cpuusage: processing output trace\n    cpuusage: completed processing 104 samples\n    $ xdg-open cutrace4.html\n\nResulting visualization:\n![culog4 screenshot](/doc/culog4.png)\n\n**Tracing process durations:**\n\n    $ cpuusage -v -o cutrace5.html -p ./ex005.sh\n    cpuusage: https://github.com/d99kris/cpuusage\n    cpuusage: initializing\n    cpuusage: starting program ./ex005.sh\n    cpuusage: processing output trace\n    cpuusage: completed processing 5 samples\n\nResulting visualization:\n![culog5 screenshot](/doc/culog5.png)\n\nAlternatives\n============\nThere are many CPU profilers available for Linux and macOS. Most of them are\nsample-based, and here is a list of some of them:\n- Gperftools\n- Gprof\n- Instruments - Time Profiler\n- Valgrind - Callgrind\n\nTechnical Details\n=================\nRefer to [ext/README.md](/ext/README.md) for details on the external components\nused by cpuusage.\n\nLicense\n=======\nCpuusage is distributed under the BSD 3-Clause license. See LICENSE file.\n\nKeywords\n========\nlinux, macos, cpu usage, instrumented profiler, alternative to callgrind.\n","funding_links":[],"categories":["1. System Overview"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd99kris%2Fcpuusage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd99kris%2Fcpuusage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd99kris%2Fcpuusage/lists"}