{"id":13765679,"url":"https://github.com/kdab/hotspot","last_synced_at":"2026-03-05T23:31:10.045Z","repository":{"id":37396704,"uuid":"76978254","full_name":"KDAB/hotspot","owner":"KDAB","description":"The Linux perf GUI for performance analysis.","archived":false,"fork":false,"pushed_at":"2025-05-07T13:54:54.000Z","size":9396,"stargazers_count":4400,"open_issues_count":64,"forks_count":261,"subscribers_count":95,"default_branch":"master","last_synced_at":"2025-05-20T20:04:51.625Z","etag":null,"topics":["cpp","cpu-profiling","linux","perf","performance","performance-analysis","profiler","profiling","qt"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KDAB.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.GPL.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-12-20T17:38:04.000Z","updated_at":"2025-05-20T17:53:14.000Z","dependencies_parsed_at":"2023-09-25T13:20:59.274Z","dependency_job_id":"6ae27aae-316c-492b-8bde-d03c7f9b137f","html_url":"https://github.com/KDAB/hotspot","commit_stats":{"total_commits":1560,"total_committers":66,"mean_commits":"23.636363636363637","dds":"0.24615384615384617","last_synced_commit":"36bedef070d5b846d2be416e96a860220904e14a"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/KDAB/hotspot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KDAB%2Fhotspot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KDAB%2Fhotspot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KDAB%2Fhotspot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KDAB%2Fhotspot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KDAB","download_url":"https://codeload.github.com/KDAB/hotspot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KDAB%2Fhotspot/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260458530,"owners_count":23012495,"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":["cpp","cpu-profiling","linux","perf","performance","performance-analysis","profiler","profiling","qt"],"created_at":"2024-08-03T16:00:43.949Z","updated_at":"2026-01-16T13:06:36.882Z","avatar_url":"https://github.com/KDAB.png","language":"C++","readme":"\u003cimg width=\"100%\" src=\"src/images/hotspot-logo.png\"\u003e\n\n# Hotspot - the Linux perf GUI for performance analysis\n\nThis project is a [KDAB](https://www.kdab.com) R\u0026D effort to create a standalone\nGUI for performance data. As the first goal, we want to provide a UI like\nKCachegrind around Linux perf. Looking ahead, we intend to support various other\nperformance data formats under this umbrella.\n\n## Table of Contents\n\n\u003c!--\n    TOC generated with https://github.com/jonschlinkert/markdown-toc\n    To update, run `markdown-toc -i README.md`\n--\u003e\n\n\u003c!-- toc --\u003e\n\n- [Screenshots](#screenshots)\n  - [Visualizing Data](#visualizing-data)\n  - [Time Line](#time-line)\n  - [Record Data](#record-data)\n- [Getting Hotspot](#getting-hotspot)\n  - [Gentoo](#gentoo)\n  - [Via package manager](#via-package-manager)\n  - [For any Linux distro: AppImage](#for-any-linux-distro-appimage)\n- [Building Hotspot](#building-hotspot)\n- [Using](#using)\n  - [Off-CPU Profiling](#off-cpu-profiling)\n  - [Embedded Systems](#embedded-systems)\n  - [Import Export](#import-export)\n  - [tracepoints](#tracepoints)\n  - [Disassembler](#disassembler)\n- [Known Issues](#known-issues)\n  - [Broken Backtraces](#broken-backtraces)\n  - [debuginfod](#debuginfod)\n  - [Missing Features](#missing-features)\n  - [Recording with perf without super user rights](#recording-with-perf-without-super-user-rights)\n  - [Export File Format](#export-file-format)\n- [Qt Creator](#qt-creator)\n- [License](#license)\n\n\u003c!-- tocstop --\u003e\n\n## Screenshots\n\nHere are some screenshots showing the most important features of Hotspot in action:\n\n### Visualizing Data\n\nThe main feature of Hotspot is the graphical visualization of a `perf.data` file.\n\n![hotspot summary page](screenshots/summary.png?raw=true \"Hotspot summary page\")\n\n![hotspot FlameGraph page](screenshots/flamegraph.png?raw=true \"Hotspot FlameGraph page\")\n\nNote: Inlined functions have a darker border than non-inlined ones.\n\n![hotspot off-CPU analysis](screenshots/off-cpu.png?raw=true \"hotspot off-CPU analysis\")\n\n![hotspot caller-callee page](screenshots/caller-callee.png?raw=true \"Hotspot caller-callee page\")\n\n![hotspot bottom-up page](screenshots/bottom-up.png?raw=true \"Hotspot bottom-up page\")\n\n![hotspot top-down page](screenshots/top-down.png?raw=true \"Hotspot top-down page\")\n\n![hotspot dockwidget layouts](screenshots/dockwidgets.png?raw=true\n\"Hotspot with custom dockwidget layout and disassembly view\")\n\n### Time Line\n\nThe time line allows filtering the results by time, process or thread. The data views are updated accordingly.\n\n![hotspot timeline filtering by time](screenshots/timeline-filter-time.png?raw=true\n\"Hotspot timeline filtering by time\")\n\n![hotspot timeline filtering by thread or process](screenshots/timeline-filter-thread.png?raw=true\n\"Hotspot timeline filtering by thread or process\")\n\n![hotspot timeline filtering applied to FlameGraph](screenshots/timeline-flamegraph.png?raw=true\n\"Hotspot timeline filtering also applies to the data views on top, like e.g. the FlameGraph.\nYou can also zoom in on the timeline and inspect individual sample data.\")\n\n### Record Data\n\nYou can also launch `perf` from Hotspot, to profile a newly started application\nor to attach to already running process(es). Do take the\n[caveats below](#recording-with-perf-without-super-user-rights) into account though.\n\n![hotspot launch application](screenshots/record-launch.png?raw=true\n\"Hotspot can launch a new application and profile it with perf from the record page.\")\n\n![hotspot attach to process](screenshots/record-attach.png?raw=true\n\"Hotspot also allows runtime-attaching of perf to existing applications to profile them.\")\n\n## Getting Hotspot\n\n*Note: Hotspot is not yet packaged on all Linux distributions. In such cases, or if you want to use the\nlatest version, please use the AppImage which will work on any recent Linux distro just fine.*\n\n### Gentoo\n\nHotspot ebuilds are available from our overlay (https://github.com/KDAB/kdab-overlay).\n\n### Via package manager\n\n[![Packaging status](https://repology.org/badge/vertical-allrepos/hotspot-perf.svg)](https://repology.org/project/hotspot-perf/versions)\n\n### For any Linux distro: AppImage\n\nYou can either head over to the most [current release](https://github.com/KDAB/hotspot/releases/latest)\nor the [continuous build](https://github.com/KDAB/hotspot/releases/tag/continuous).\nIn both cases you'll find the AppImage under \"Assets\" that you can download.\nUntar the AppImage file (in case of the latest release), then make it executable and then run it.\n\nPlease use the latest build to get the most recent version. If it doesn't work, please report a\nbug and test the latest stable version.\n\n*Note: Your system libraries or preferences are not altered. In case you'd like to remove Hotspot again,\nsimply delete the downloaded file. Learn more about AppImage [here](https://appimage.org/).*\n\nTo find out how to debug the AppImage, see [HACKING](HACKING.md#debugging-the-appimage).\n\n## Building Hotspot\n\nBuilding Hotspot from source gives you the latest and greatest, but you'll have to make sure all its\ndependencies are available. Most users should probably [install Hotspot](#getting-hotspot) from the distro\npackage manager or as an [AppImage](#for-any-linux-distro-appimage).\n\nFor everyone that wants to contribute to Hotspot or use the newest version without the AppImage detailed\nnotes are found at [HACKING](HACKING.md#table-of-contents).\n\n## Using\n\n### General\n\nFirst of all, record some data with `perf`. To get backtraces, you will need to enable the dwarf callgraph\nmode:\n\n```bash\nperf record --call-graph dwarf \u003cyour application\u003e\n...\n[ perf record: Woken up 58 times to write data ]\n[ perf record: Captured and wrote 14.874 MB perf.data (1865 samples) ]\n```\n\nNow, if you have Hotspot available on the same machine, all you need to do is launch it.\nIt will automatically open the `perf.data` file in the current directory (similar to `perf report`).\n\nAlternatively, you can specify the path to the data file on the console:\n\n```bash\nhotspot /path/to/perf.data\n```\n\n### Command Line options\n\nDepending on your needs you may want to pass additional command line options to Hotspot.\nThis allows to one-time set configuration options that are found in the GUI under \"Settings\"\nand also allows to convert Linux perf data files into the smaller and portable perfdata format\n(see [Import / Export](#import-export) for details on that).\nAll command line options are shown with `--help`:\n\n```text\nUsage: hotspot [options] [files...]\nLinux perf GUI for performance analysis.\n\nOptions:\n  -h, --help               Displays help on commandline options.\n  --help-all               Displays help including Qt specific options.\n  -v, --version            Displays version information.\n  --sysroot \u003cpath\u003e         Path to sysroot which is used to find libraries.\n  --kallsyms \u003cpath\u003e        Path to kallsyms file which is used to resolve\n                           kernel symbols.\n  --debugPaths \u003cpaths\u003e     Colon separated list of paths that contain debug\n                           information. These paths are relative to the\n                           executable and not to the current working directory.\n  --extraLibPaths \u003cpaths\u003e  Colon separated list of extra paths to find\n                           libraries.\n  --appPath \u003cpath\u003e         Path to folder containing the application executable\n                           and libraries.\n  --sourcePaths \u003cpaths\u003e    Colon separated list of search paths for the source\n                           code.\n  --arch \u003cpath\u003e            Architecture to use for unwinding.\n  --exportTo \u003cpath\u003e        Path to .perfparser output file to which the input\n                           data should be exported. A single input file has to\n                           be given too.\n  --perf-binary \u003cpath\u003e     Path to the perf binary.\n  --objdump-binary \u003cpath\u003e  Path to the objdump binary.\n\nArguments:\n  files                    Optional input files to open on startup, i.e.\n                           perf.data files.\n```\n\n### Off-CPU Profiling\n\nHotspot supports a very powerful way of doing wait-time analysis, or off-CPU profiling.\nThis analysis is based on kernel tracepoints in the linux scheduler. By recording that\ndata, we can find the time delta during which a thread was not running on the CPU, but\ninstead was off-CPU. There can be multiple reasons for that, all of which can be found\nusing this technique:\n\n- synchronous I/O, e.g. via `read()` or `write()`\n- page faults, e.g. when accessing `mmap()`'ed file data\n- calls to `nanosleep()` or `yield()`\n- lock contention via `futex()` etc.\n- preemption\n- and probably many more\n\nBy leveraging kernel trace points in the scheduler, the overhead is pretty manageable\nand we only pay a price, when the process is actually getting switched out. Most notably\nwe do not pay a price when e.g. a mutex lock operation can be handled directly in\nuser-space.\n\nTo do off-CPU analysis with Hotspot, you need to record the data with a very specific\ncommand:\n\n```bash\nperf record \\\n    -e cycles \\                             # on-CPU profiling\n    -e sched:sched_switch --switch-events \\ # off-CPU profiling\n    --sample-cpu \\                          # track on which core code is executed\n    -m 8M \\                                 # reduce chance of event loss\n    --aio -z \\                              # reduce disk-I/O overhead and data size\n    --call-graph dwarf \\                    # we definitely want backtraces\n    \u003cyour application\u003e\n```\n\nAlternatively, you can use the off-CPU check box in Hotspot's integrated record page.\n\nDuring the analysis, you can then switch between the \"cycles\" cost view for on-CPU data\nto the \"off-CPU time\" cost view for wait-time analysis. Often, you will want to change\nbetween both, e.g. to find places in your code which may require further parallelization\n(see also [Amdahl's law](https://en.wikipedia.org/wiki/Amdahl%27s_law)).\n\nThe \"sched:sched_switch\" cost will also be shown to you. But in my opinion that is less\nuseful, as it only indicates the number of scheduler switches. The length of the time\ninbetween is often way more interesting to me - and that's what is shown to you in the\n\"off-CPU time\" metric.\n\n### Embedded Systems\n\nIf you are recording on an embedded system, you will want to analyze the data on your\ndevelopment machine with Hotspot. To do so, make sure your sysroot contains the debug\ninformation required for unwinding (see below). Then record the data on your embedded\nsystem:\n\n```bash\nembedded$ perf record --call-graph dwarf \u003cyour application\u003e\n...\n[ perf record: Woken up 58 times to write data ]\n[ perf record: Captured and wrote 14.874 MB perf.data (1865 samples) ]\nembedded$ cp /proc/kallsyms /tmp/kallsyms # make pseudo-file a real file\n```\n\nIt's OK if your embedded machine is using a different platform than your host. On your\nhost, do the following steps then to analyze the data:\n\n```bash\nhost$ scp embedded:perf.data embedded:/tmp/kallsyms .\nhost$ hotspot --sysroot /path/to/sysroot --kallsyms kallsyms \\\n              perf.data\n```\n\nIf you manually deployed an application from a path outside your sysroot, do this instead:\n\n```bash\nhost$ hotspot --sysroot /path/to/sysroot --kallsyms kallsyms --appPath /path/to/app \\\n              perf.data\n```\n\nIf your application is also using libraries outside your sysroot and the appPath, do this:\n\n```bash\nhost$ hotspot --sysroot /path/to/sysroot --kallsyms kallsyms --appPath /path/to/app \\\n              --extraLibPaths /path/to/lib1:/path/to/lib2:... \\\n              perf.data\n```\n\nAnd, worst-case, if you also use split debug files in non-standard locations, do this:\n\n```bash\nhost$ hotspot --sysroot /path/to/sysroot --kallsyms kallsyms --appPath /path/to/app \\\n              --extraLibPaths /path/to/lib1:/path/to/lib2:... \\\n              --debugPaths /path/to/debug1:/path/to/debug2:... \\\n              perf.data\n```\n\n### Import Export\n\nThe `perf.data` file format is not self-contained. To analyze it, you need access\nto the executables and libraries of the profiled process, together with debug symbols.\nThis makes it unwieldy to share such files across machines, e.g. to get the help from\na colleague to investigate a performance issue, or for bug reporting purposes.\n\nHotspot allows you to export the analyzed data, which is then fully self-contained.\nThis feature is accessible via the \"File \u003e Save As\" menu action. The data is then\nsaved in a self-contained `*.perfparser` file. To import the data into Hotspot again,\njust open that file directly in place of the original `perf.data` file.\n\nAs an alternative you can also do the export from command line (without a GUI, so that's\nalso usable with automated builds) using the `--exportTo` option.\n\n**Note:** The file format is _not_ yet stable. Meaning data exported by one version\nof Hotspot can only be read back in by the same version. This problem will be\nresolved in the future, as time permits.\n\n### tracepoints\n\nHotspot currently only shows the name of the tracepoints in the timeline.\n\n![hotspot tracepoints](screenshots/tracepoints.png?raw=true \"Hotspot tracepoints\")\n\n### Disassembler\n\n![hotspot disassembler page](screenshots/disassembler.png?raw=true \"Hotspot disassembler page\")\n\nHotspot includes an disassembler, which can show you the cost per instruction.\nThe disassembler uses colors to indicate which assembly lines correspond to\nwhich source code line.\nFor easier navigation, you can simply click on a line and the other view will jump to it.\nYou can follow function calls with a double click.\nIn the sourcecode view you can press ctrl+f or press the search icon to open a search window.\n\nIf you have the sources in different directory, you can use `--sourcePaths` or the settings to\nselect tell the disassembler to search there for the source code.\n\n## Known Issues\n\nIf anything breaks in the above and the output is less usable than `perf report`, please\n[report an issue on GitHub](https://github.com/KDAB/hotspot/issues).\nThat said, there are some known issues that people may trip over:\n\n### Broken Backtraces\n\nUnwinding the stack to produce a backtrace is a dark art and can go wrong in many ways.\nHotspot relies on `perfparser` (see below), which in turn relies on `libdw` from elfutils\nto unwind the stack. This works quite well most of the time, but still can go wrong. Most\nnotably, unwinding will fail when:\n\n- an ELF file (i.e. executable or library) referenced by the `perf.data` file is missing\n  - to fix this, try to use one of the following CLI arguments to let Hotspot know where to look for the\n    ELF files:\n    - `--debugPaths \u003cpaths\u003e`: Use this when you have split debug files in non-standard locations\n    - `--extraLibPaths \u003cpaths\u003e`: Use this when you have moved libraries to some other location since recording\n    - `--appPath \u003cpaths\u003e`: This is kind of a combination of the above two fields. The path is traversed\n     recursively, looking for debug files and libraries.\n    - `--sysroot \u003cpath\u003e`: Use this when you try to inspect a data file recorded on an embedded platform\n- an ELF file is missing debug information\n  - to fix this, install the debug package from your distro\n  - or compile the code in \"release with debug\" mode, i.e. ensure your compiler is invoked with something\n    like `-O2 -g`. You will have to repeat the `perf record` step\n  - potentially both of the above is not an option for you, e.g. when the library is closed source and\n    supplied by a thirdparty vendor. If that is the case,\n    you may be lucky and the library contains frame pointers. If so, then try to build elfutils from current\n    git master (you want commit a55df2c1, which should be part of 0.170).\n    This version of elfutils will try to fallback to the frame pointer for unwinding, when the debug\n    information is missing.\n- your call stacks are too deep\n  - by default, `perf record` only copies a part of the stack to the data file. This can lead to issues with\n    very deep call stacks, which will be cut off at some point. This issue will break the top-down call trees\n    in Hotspot, as visualized in the Top-Down view or the Flame Graph. To fix this, you can try to increase\n    the stack dump size, i.e.:\n\n        perf record --call-graph dwarf,32768\n\n    Note that this can dramatically increase the size of the `perf.data` files - use it with care. Also have a\n    look at `man perf record`.\n  - For some scenarios, recursive function calls simply fail to be unwound. See also\n    https://github.com/KDAB/hotspot/issues/93\n\n### debuginfod\n\nHotspot supports downloading debug symbols via [debuginfod](https://sourceware.org/elfutils/Debuginfod.html).\nThis can be enabled by either adding download urls in the settings or launching Hotspot with `DEBUGINFOD_URLS`\ndefined in the environment.\n\n### Missing Features\n\nCompared to `perf report`, Hotspot misses a lot of features. Some of these are planned to be resolved\nin the future. Others may potentially never get implemented. But be aware that the following features\nare _not_ available in Hotspot currently:\n\n- the columns in the tables are currently hardcoded, while potentially a user may want to change this to show\n  e.g. cost per-process or thread and so forth. Basic group-by functionality was added, but a more flexible\n  column arrangement a la WPA is not planned for now.\n- many of the more advanced features, such as `--itrace`, `--mem-mode`, `--branch-stack` and\n  `--branch-history`, are unsupported\n\n### Recording with perf without super user rights\n\nIt is **not** a good idea to launch Hotspot with `sudo` or as `root` user. See e.g.\n[Editing Files As Root](https://blog.martin-graesslin.com/blog/2017/02/editing-files-as-root/)\nfor an article on that matter. [Issue #83](https://github.com/KDAB/hotspot/issues/83) is\nalso relevant in this contact.\n\nBut without superuser rights, you may see error messages such as the following\nwhen using Hotspot's record feature:\n\n```text\nYou may not have permission to collect stats.\nConsider tweaking /proc/sys/kernel/perf_event_paranoid:\n  -1 - Not paranoid at all\n   0 - Disallow raw tracepoint access for unpriv\n   1 - Disallow cpu events for unpriv\n   2 - Disallow kernel profiling for unpriv\n```\n\nTo workaround this limitation, Hotspot can run perf itself with elevated privileges.\n\n### Export File Format\n\nThe current data export is limited to a format that can only be read back by Hotspot of the same\nversion. This makes interop with other visualization tools quasi impossible. This is known and\nwill get improved in the future. Most notably support for export to web viewers such as\n[perfetto](https://perfetto.dev/) or the [Mozilla profiler](https://profiler.firefox.com/) is\nplanned but not yet implemented. Patches welcome!\n\n## Qt Creator\n\nThis project leverages the excellent `perfparser` utility created by The Qt Company\nfor their Qt Creator IDE. If you are already using Qt Creator, consider leveraging\nits integrated [CPU Usage Analyzer](https://doc.qt.io/qtcreator/creator-cpu-usage-analyzer.html).\n\n## License\n\nHotspot is licensed under the GPL v2+. See [LICENSE.GPL.txt](LICENSE.GPL.txt) for more information,\nor contact info@kdab.com if any conditions of this licensing are not clear to you.\n","funding_links":[],"categories":["Linux"],"sub_categories":["Performance"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkdab%2Fhotspot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkdab%2Fhotspot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkdab%2Fhotspot/lists"}