Convert Figma logo to code with AI

KDAB logohotspot

The Linux perf GUI for performance analysis.

4,059
250
4,059
56
View on GitHub

Top Related Projects

google's avatar

benchmark

8,962

A microbenchmark support library

microsoft's avatar

perfview

4,106

PerfView is a CPU and memory performance-analysis tool

gperftools's avatar

gperftools

8,418

Main gperftools repository

Quick Overview

Hotspot is a performance profiling tool for Linux, macOS, and Windows that provides detailed information about CPU usage, memory usage, and other system metrics. It is designed to help developers and system administrators identify performance bottlenecks and optimize their applications.

Pros

  • Detailed Profiling: Hotspot provides a comprehensive view of system performance, including CPU usage, memory usage, disk I/O, and network activity.
  • Cross-Platform Support: The tool can be used on Linux, macOS, and Windows, making it a versatile choice for developers working on different platforms.
  • Easy to Use: Hotspot has a user-friendly interface that makes it easy to navigate and analyze performance data.
  • Open-Source: The project is open-source, allowing developers to contribute to the project and customize the tool to their needs.

Cons

  • Limited Visualization: While Hotspot provides detailed performance data, the visualization options may be limited compared to other profiling tools.
  • Dependency on Perf: Hotspot relies on the Linux perf tool, which may not be available on all systems or may require additional setup.
  • Windows Support: The Windows support in Hotspot is relatively new and may not be as mature as the Linux and macOS support.
  • Learning Curve: Interpreting the performance data provided by Hotspot may require some learning and experience, especially for users new to performance profiling.

Code Examples

Hotspot is a GUI application, so there are no code examples to provide. However, you can use the tool to profile your application and analyze the performance data.

Getting Started

To get started with Hotspot, follow these steps:

  1. Clone the GitHub repository:
git clone https://github.com/KDAB/hotspot.git
  1. Build the project:
cd hotspot
mkdir build
cd build
cmake ..
make
  1. Run the Hotspot application:
./bin/hotspot

  1. In the Hotspot application, you can start profiling your application by clicking the "Record" button. Hotspot will then collect performance data and display it in the user interface.

  2. Analyze the performance data and identify any bottlenecks or areas for optimization.

For more detailed instructions and information on using Hotspot, please refer to the project's README and documentation.

Competitor Comparisons

google logo

benchmark

8,962

A microbenchmark support library

Pros of google/benchmark

  • Supports a wide range of programming languages, including C++, C, and Python.
  • Provides a comprehensive set of benchmarking features, including support for custom metrics and statistical analysis.
  • Has a large and active community, with regular updates and contributions.

Cons of google/benchmark

  • May have a steeper learning curve compared to KDAB/hotspot, especially for users who are not familiar with the Google Test framework.
  • Requires more configuration and setup compared to the more user-friendly KDAB/hotspot.
  • May not be as well-suited for profiling complex, real-world applications as KDAB/hotspot.

Code Comparison

KDAB/hotspot:

void MyClass::myFunction() {
    // Some code
    int x = 42;
    // More code
    return x;
}

google/benchmark:

static void BM_MyFunction(benchmark::State& state) {
    for (auto _ : state) {
        int x = 42;
        benchmark::DoNotOptimize(x);
    }
}
BENCHMARK(BM_MyFunction);
microsoft logo

perfview

4,106

PerfView is a CPU and memory performance-analysis tool

Pros of PerfView

  • PerfView provides a more comprehensive set of performance analysis tools, including CPU profiling, memory analysis, and event tracing.
  • PerfView has a larger user community and more extensive documentation, making it easier for new users to get started.
  • PerfView is actively maintained and regularly updated by Microsoft.

Cons of PerfView

  • PerfView is primarily focused on Windows-based systems, while Hotspot is cross-platform and supports Linux and macOS.
  • PerfView's user interface may be less intuitive and more complex for some users compared to Hotspot.
  • PerfView is a standalone application, while Hotspot is a command-line tool that can be more easily integrated into existing workflows.

Code Comparison

PerfView:

public static void Main(string[] args)
{
    var app = new App();
    app.InitializeComponent();
    app.Run();
}

Hotspot:

int main(int argc, char** argv)
{
    Hotspot hotspot;
    return hotspot.run(argc, argv);
}

Both the PerfView and Hotspot code snippets show the entry point of their respective applications. PerfView uses a C# Main method and a WPF application, while Hotspot uses a C++ main function and a custom Hotspot class to handle the application logic.

gperftools logo

gperftools

8,418

Main gperftools repository

Pros of gperftools/gperftools

  • Supports a wider range of platforms, including Windows and macOS, in addition to Linux.
  • Provides a comprehensive set of profiling tools, including CPU profiler, heap profiler, and memory leak detector.
  • Offers a simple and easy-to-use API for integrating profiling into your application.

Cons of gperftools/gperftools

  • Requires manual instrumentation of the code to be profiled, which can be time-consuming and error-prone.
  • May have higher overhead compared to sampling-based profilers like KDAB/hotspot.
  • Lacks some of the advanced features and visualizations provided by KDAB/hotspot.

Code Comparison

gperftools/gperftools:

#include <gperftools/profiler.h>

int main() {
    ProfilerStart("profile.out");
    // Your application code here
    ProfilerStop();
    return 0;
}

KDAB/hotspot:

#include <KHotKeys/KHotKeys.h>

int main() {
    KHotKeys::start();
    // Your application code here
    KHotKeys::stop();
    return 0;
}

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Hotspot - the Linux perf GUI for performance analysis

This project is a KDAB R&D effort to create a standalone GUI for performance data. As the first goal, we want to provide a UI like KCachegrind around Linux perf. Looking ahead, we intend to support various other performance data formats under this umbrella.

Table of Contents

Screenshots

Here are some screenshots showing the most important features of Hotspot in action:

Visualizing Data

The main feature of Hotspot is the graphical visualization of a perf.data file.

hotspot summary page

hotspot FlameGraph page

Note: Inlined functions have a darker border than non-inlined ones.

hotspot off-CPU analysis

hotspot caller-callee page

hotspot bottom-up page

hotspot top-down page

hotspot dockwidget layouts

Time Line

The time line allows filtering the results by time, process or thread. The data views are updated accordingly.

hotspot timeline filtering by time

hotspot timeline filtering by thread or process

hotspot timeline filtering applied to FlameGraph

Record Data

You can also launch perf from Hotspot, to profile a newly started application or to attach to already running process(es). Do take the caveats below into account though.

hotspot launch application

hotspot attach to process

Getting Hotspot

Note: Hotspot is not yet packaged on all Linux distributions. In such cases, or if you want to use the latest version, please use the AppImage which will work on any recent Linux distro just fine.

ArchLinux

Hotspot is available in AUR (https://aur.archlinux.org/packages/hotspot).

Debian / Ubuntu

Hotspot is available in Debian (https://packages.debian.org/hotspot) and Ubuntu (https://packages.ubuntu.com/hotspot).

Gentoo

Hotspot ebuilds are available from our overlay (https://github.com/KDAB/kdab-overlay).

Fedora

Hotspot is available in Fedora (https://packages.fedoraproject.org/pkgs/hotspot/hotspot/).

For any Linux distro: AppImage

You can either head over to the most current release or the continuous build. In both cases you'll find the AppImage under "Assets" that you can download. Untar the AppImage file (in case of the latest release), then make it executable and then run it.

Please use the latest build to get the most recent version. If it doesn't work, please report a bug and test the latest stable version.

Note: Your system libraries or preferences are not altered. In case you'd like to remove Hotspot again, simply delete the downloaded file. Learn more about AppImage here.

To find out how to debug the AppImage, see HACKING.

Building Hotspot

Building Hotspot from source gives you the latest and greatest, but you'll have to make sure all its dependencies are available. Most users should probably install Hotspot from the distro package manager or as an AppImage.

For everyone that wants to contribute to Hotspot or use the newest version without the AppImage detailed notes are found at HACKING.

Using

General

First of all, record some data with perf. To get backtraces, you will need to enable the dwarf callgraph mode:

perf record --call-graph dwarf <your application>
...
[ perf record: Woken up 58 times to write data ]
[ perf record: Captured and wrote 14.874 MB perf.data (1865 samples) ]

Now, if you have Hotspot available on the same machine, all you need to do is launch it. It will automatically open the perf.data file in the current directory (similar to perf report).

Alternatively, you can specify the path to the data file on the console:

hotspot /path/to/perf.data

Command Line options

Depending on your needs you may want to pass additional command line options to Hotspot. This allows to one-time set configuration options that are found in the GUI under "Settings" and also allows to convert Linux perf data files into the smaller and portable perfdata format (see Import / Export for details on that). All command line options are shown with --help:

Usage: hotspot [options] [files...]
Linux perf GUI for performance analysis.

Options:
  -h, --help               Displays help on commandline options.
  --help-all               Displays help including Qt specific options.
  -v, --version            Displays version information.
  --sysroot <path>         Path to sysroot which is used to find libraries.
  --kallsyms <path>        Path to kallsyms file which is used to resolve
                           kernel symbols.
  --debugPaths <paths>     Colon separated list of paths that contain debug
                           information. These paths are relative to the
                           executable and not to the current working directory.
  --extraLibPaths <paths>  Colon separated list of extra paths to find
                           libraries.
  --appPath <path>         Path to folder containing the application executable
                           and libraries.
  --sourcePaths <paths>    Colon separated list of search paths for the source
                           code.
  --arch <path>            Architecture to use for unwinding.
  --exportTo <path>        Path to .perfparser output file to which the input
                           data should be exported. A single input file has to
                           be given too.
  --perf-binary <path>     Path to the perf binary.
  --objdump-binary <path>  Path to the objdump binary.

Arguments:
  files                    Optional input files to open on startup, i.e.
                           perf.data files.

Off-CPU Profiling

Hotspot supports a very powerful way of doing wait-time analysis, or off-CPU profiling. This analysis is based on kernel tracepoints in the linux scheduler. By recording that data, we can find the time delta during which a thread was not running on the CPU, but instead was off-CPU. There can be multiple reasons for that, all of which can be found using this technique:

  • synchronous I/O, e.g. via read() or write()
  • page faults, e.g. when accessing mmap()'ed file data
  • calls to nanosleep() or yield()
  • lock contention via futex() etc.
  • preemption
  • and probably many more

By leveraging kernel trace points in the scheduler, the overhead is pretty manageable and we only pay a price, when the process is actually getting switched out. Most notably we do not pay a price when e.g. a mutex lock operation can be handled directly in user-space.

To do off-CPU analysis with Hotspot, you need to record the data with a very specific command:

perf record \
    -e cycles \                             # on-CPU profiling
    -e sched:sched_switch --switch-events \ # off-CPU profiling
    --sample-cpu \                          # track on which core code is executed
    -m 8M \                                 # reduce chance of event loss
    --aio -z \                              # reduce disk-I/O overhead and data size
    --call-graph dwarf \                    # we definitely want backtraces
    <your application>

Alternatively, you can use the off-CPU check box in Hotspot's integrated record page.

During the analysis, you can then switch between the "cycles" cost view for on-CPU data to the "off-CPU time" cost view for wait-time analysis. Often, you will want to change between both, e.g. to find places in your code which may require further parallelization (see also Amdahl's law).

The "sched:sched_switch" cost will also be shown to you. But in my opinion that is less useful, as it only indicates the number of scheduler switches. The length of the time inbetween is often way more interesting to me - and that's what is shown to you in the "off-CPU time" metric.

Embedded Systems

If you are recording on an embedded system, you will want to analyze the data on your development machine with Hotspot. To do so, make sure your sysroot contains the debug information required for unwinding (see below). Then record the data on your embedded system:

embedded$ perf record --call-graph dwarf <your application>
...
[ perf record: Woken up 58 times to write data ]
[ perf record: Captured and wrote 14.874 MB perf.data (1865 samples) ]
embedded$ cp /proc/kallsyms /tmp/kallsyms # make pseudo-file a real file

It's OK if your embedded machine is using a different platform than your host. On your host, do the following steps then to analyze the data:

host$ scp embedded:perf.data embedded:/tmp/kallsyms .
host$ hotspot --sysroot /path/to/sysroot --kallsyms kallsyms \
              perf.data

If you manually deployed an application from a path outside your sysroot, do this instead:

host$ hotspot --sysroot /path/to/sysroot --kallsyms kallsyms --appPath /path/to/app \
              perf.data

If your application is also using libraries outside your sysroot and the appPath, do this:

host$ hotspot --sysroot /path/to/sysroot --kallsyms kallsyms --appPath /path/to/app \
              --extraLibPaths /path/to/lib1:/path/to/lib2:... \
              perf.data

And, worst-case, if you also use split debug files in non-standard locations, do this:

host$ hotspot --sysroot /path/to/sysroot --kallsyms kallsyms --appPath /path/to/app \
              --extraLibPaths /path/to/lib1:/path/to/lib2:... \
              --debugPaths /path/to/debug1:/path/to/debug2:... \
              perf.data

Import Export

The perf.data file format is not self-contained. To analyze it, you need access to the executables and libraries of the profiled process, together with debug symbols. This makes it unwieldy to share such files across machines, e.g. to get the help from a colleague to investigate a performance issue, or for bug reporting purposes.

Hotspot allows you to export the analyzed data, which is then fully self-contained. This feature is accessible via the "File > Save As" menu action. The data is then saved in a self-contained *.perfparser file. To import the data into Hotspot again, just open that file directly in place of the original perf.data file.

As an alternative you can also do the export from command line (without a GUI, so that's also usable with automated builds) using the --exportTo option.

Note: The file format is not yet stable. Meaning data exported by one version of Hotspot can only be read back in by the same version. This problem will be resolved in the future, as time permits.

tracepoints

Hotspot currently only shows the name of the tracepoints in the timeline.

hotspot tracepoints

Disassembler

hotspot disassembler page

Hotspot includes an disassembler, which can show you the cost per instruction. The disassembler uses colors to indicate which assembly lines correspond to which source code line. For easier navigation, you can simply click on a line and the other view will jump to it. You can follow function calls with a double click. In the sourcecode view you can press ctrl+f or press the search icon to open a search window.

If you have the sources in different directory, you can use --sourcePaths or the settings to select tell the disassembler to search there for the source code.

Known Issues

If anything breaks in the above and the output is less usable than perf report, please report an issue on GitHub. That said, there are some known issues that people may trip over:

Broken Backtraces

Unwinding the stack to produce a backtrace is a dark art and can go wrong in many ways. Hotspot relies on perfparser (see below), which in turn relies on libdw from elfutils to unwind the stack. This works quite well most of the time, but still can go wrong. Most notably, unwinding will fail when:

  • an ELF file (i.e. executable or library) referenced by the perf.data file is missing
    • to fix this, try to use one of the following CLI arguments to let Hotspot know where to look for the ELF files:
      • --debugPaths <paths>: Use this when you have split debug files in non-standard locations
      • --extraLibPaths <paths>: Use this when you have moved libraries to some other location since recording
      • --appPath <paths>: This is kind of a combination of the above two fields. The path is traversed recursively, looking for debug files and libraries.
      • --sysroot <path>: Use this when you try to inspect a data file recorded on an embedded platform
  • an ELF file is missing debug information
    • to fix this, install the debug package from your distro
    • or compile the code in "release with debug" mode, i.e. ensure your compiler is invoked with something like -O2 -g. You will have to repeat the perf record step
    • potentially both of the above is not an option for you, e.g. when the library is closed source and supplied by a thirdparty vendor. If that is the case, you may be lucky and the library contains frame pointers. If so, then try to build elfutils from current git master (you want commit a55df2c1, which should be part of 0.170). This version of elfutils will try to fallback to the frame pointer for unwinding, when the debug information is missing.
  • your call stacks are too deep

    • by default, perf record only copies a part of the stack to the data file. This can lead to issues with very deep call stacks, which will be cut off at some point. This issue will break the top-down call trees in Hotspot, as visualized in the Top-Down view or the Flame Graph. To fix this, you can try to increase the stack dump size, i.e.:

      perf record --call-graph dwarf,32768

      Note that this can dramatically increase the size of the perf.data files - use it with care. Also have a look at man perf record.

    • For some scenarios, recursive function calls simply fail to be unwound. See also https://github.com/KDAB/hotspot/issues/93

debuginfod

Hotspot supports downloading debug symbols via debuginfod. This can be enabled by either adding download urls in the settings or launching Hotspot with DEBUGINFOD_URLS defined in the environment.

Missing Features

Compared to perf report, Hotspot misses a lot of features. Some of these are planned to be resolved in the future. Others may potentially never get implemented. But be aware that the following features are not available in Hotspot currently:

  • the columns in the tables are currently hardcoded, while potentially a user may want to change this to show e.g. cost per-process or thread and so forth. Basic group-by functionality was added, but a more flexible column arrangement a la WPA is not planned for now.
  • many of the more advanced features, such as --itrace, --mem-mode, --branch-stack and --branch-history, are unsupported

Recording with perf without super user rights

It is not a good idea to launch Hotspot with sudo or as root user. See e.g. Editing Files As Root for an article on that matter. Issue #83 is also relevant in this contact.

But without superuser rights, you may see error messages such as the following when using Hotspot's record feature:

You may not have permission to collect stats.
Consider tweaking /proc/sys/kernel/perf_event_paranoid:
  -1 - Not paranoid at all
   0 - Disallow raw tracepoint access for unpriv
   1 - Disallow cpu events for unpriv
   2 - Disallow kernel profiling for unpriv

To workaround this limitation, Hotspot can run perf itself with elevated privileges.

Export File Format

The current data export is limited to a format that can only be read back by Hotspot of the same version. This makes interop with other visualization tools quasi impossible. This is known and will get improved in the future. Most notably support for export to web viewers such as perfetto or the Mozilla profiler is planned but not yet implemented. Patches welcome!

Qt Creator

This project leverages the excellent perfparser utility created by The Qt Company for their Qt Creator IDE. If you are already using Qt Creator, consider leveraging its integrated CPU Usage Analyzer.

License

Hotspot is licensed under the GPL v2+. See LICENSE.GPL.txt for more information, or contact info@kdab.com if any conditions of this licensing are not clear to you.