Skip to content

Commit

Permalink
docs: update, mostly for AppImage notes
Browse files Browse the repository at this point in the history 
README.md:
* updated AppImage notes - point to latest/continuous release instead of CI artifacts
* case adjustments for Hotspot and AppImage
* http -> https
* some minor rewording

HACKING.md:
* drop the unzip step as it is not needed any more
* replace shown version string by a clear pseudo-version
* update shown dates to a more current one
  • Loading branch information
@GitMensch @milianw
GitMensch authored and milianw committed May 31, 2024
1 parent 0c8f219 commit 0131bbd
Show file tree
Hide file tree
Showing 2 changed files with 74 additions and 74 deletions.
32 changes: 15 additions & 17 deletions HACKING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -153,22 +153,20 @@ To do that, you will need to download the debuginfo artifact that matches the Ap

### AppImage-Debugging using manual symbol loading

For using this approach you need to first unpack the debug information:
For using this approach you need to first unpack the debug information
downloaded from the release:

```bash
$ unzip debuginfo.zip
Archive: debuginfo.zip
inflating: hotspot-debuginfo-v1.4.0-43-g02fd82c-x86_64.tar.bz2
$ tar -xvf hotspot-debuginfo-*.tar.bz2
hotspot-debuginfo-v1.4.0-43-g02fd82c/usr/bin/hotspot
hotspot-debuginfo-v1.4.0-43-g02fd82c/usr/lib64/libexec/hotspot-perfparser
hotspot-debuginfo-v1.2.3-45-g02fd82c/usr/bin/hotspot
hotspot-debuginfo-v1.2.3-45-g02fd82c/usr/lib64/libexec/hotspot-perfparser
```

Starting the debugger is possible directly with executing the AppImage as follows:

```bash
$ ./hotspot-v1.4.0-43-g02fd82c-x86_64.AppImage &
$ gdb -q -p $(pidof hotspot) -ex "add-symbol-file hotspot-debuginfo-v1.4.0-43-g02fd82c/usr/bin/hotspot"
$ ./hotspot-v1.2.3-45-g02fd82c-x86_64.AppImage &
$ gdb -q -p $(pidof hotspot) -ex "add-symbol-file hotspot-debuginfo-v1.2.3-45-g02fd82c/usr/bin/hotspot"
Attaching to process 123456
```

Expand All @@ -182,9 +180,9 @@ Reading symbols from /tmp/.mount_hotspoBCRbef/squashfs-root/usr/bin/../lib/libKF
(No debugging symbols found in /tmp/.mount_hotspoBCRbef/squashfs-root/usr/bin/../lib/libKF5ThreadWeaver.so.5)
...
0x00007fea98ae0a38 in poll () from /usr/lib64/libc.so.6
add symbol table from file "hotspot-debuginfo-v1.4.0-43-g02fd82c/usr/bin/hotspot"
add symbol table from file "hotspot-debuginfo-v1.2.3-45-g02fd82c/usr/bin/hotspot"
(y or n) y
Reading symbols from hotspot-debuginfo-v1.4.0-43-g02fd82c/usr/bin/hotspot...
Reading symbols from hotspot-debuginfo-v1.2.3-45-g02fd82c/usr/bin/hotspot...
(gdb) bt
#0 0x00007ff72544ca38 in poll () from /usr/lib64/libc.so.6
#1 0x00007ff7246777d7 in _xcb_in_read_block () from /usr/lib64/libxcb.so.1
Expand All @@ -211,9 +209,9 @@ Reading symbols from hotspot-debuginfo-v1.4.0-43-g02fd82c/usr/bin/hotspot...
or with an extracted image:

```bash
$ ./hotspot-v1.4.0-43-g02fd82c-x86_64.AppImage --appimage-extract
$ PATH=./squashfs-root/usr/bin:$PATH LD_LIBRARY_PATH=./squashfs-root/usr/lib64:/usr/local/lib64:/usr/lib64:./squashfs-root/usr/lib:$LD_LIBRARY_PATH gdb -q --exec=hotspot --symbols hotspot-debuginfo-v1.4.0-43-g02fd82c/usr/bin/hotspot -ex run
Reading symbols from hotspot-debuginfo-v1.4.0-43-g02fd82c/usr/bin/hotspot...
$ ./hotspot-v1.2.3-45-g02fd82c-x86_64.AppImage --appimage-extract
$ PATH=./squashfs-root/usr/bin:$PATH LD_LIBRARY_PATH=./squashfs-root/usr/lib64:/usr/local/lib64:/usr/lib64:./squashfs-root/usr/lib:$LD_LIBRARY_PATH gdb -q --exec=hotspot --symbols hotspot-debuginfo-v1.2.3-45-g02fd82c/usr/bin/hotspot -ex run
Reading symbols from hotspot-debuginfo-v1.2.3-45-g02fd82c/usr/bin/hotspot...
Starting program: /tmp/squashfs-root/usr/bin/hotspot

```
Expand Down Expand Up @@ -251,9 +249,9 @@ to use it on your host system, set:

export DEBUGINFOD_URLS="127.0.0.1:12345 https://debuginfod.centos.org/ https://debuginfod.archlinux.org"

[Fri Dec 2 19:58:56 2022] (16/16): opened database /opt/app-root/src/.debuginfod.sqlite
[Fri Dec 2 19:58:56 2022] (16/16): sqlite version 3.7.17
[Fri Dec 2 19:58:56 2022] (16/16): started http server on IPv4 IPv6 port=12345
[Fri May 24 19:58:56 2024] (16/16): opened database /opt/app-root/src/.debuginfod.sqlite
[Fri May 24 19:58:56 2024] (16/16): sqlite version 3.7.17
[Fri May 24 19:58:56 2024] (16/16): started http server on IPv4 IPv6 port=12345
...
```

Expand All @@ -262,7 +260,7 @@ the official Centos instance to get debug information for all the dependencies a
Here is one example for that using GDB:

```bash
$ ./hotspot-v1.3.0-391-g590f810-x86_64.AppImage &
$ ./hotspot-v1.2.3-45-g02fd82c-x86_64.AppImage &
$ export DEBUGINFOD_URLS="127.0.0.1:12345 https://debuginfod.centos.org/ https://debuginfod.archlinux.org"
$ gdb -q -p $(pidof hotspot)
Attaching to process 123456
Expand Down
116 changes: 59 additions & 57 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

# Hotspot - the Linux perf GUI for performance analysis

This project is a [KDAB](http://www.kdab.com) R&D effort to create a standalone
This project is a [KDAB](https://www.kdab.com) 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.
Expand All @@ -17,7 +17,7 @@ performance data formats under this umbrella.
<!-- toc -->

- [Screenshots](#screenshots)
- [Visualize Data](#visualize-data)
- [Visualizing Data](#visualizing-data)
- [Time Line](#time-line)
- [Record Data](#record-data)
- [Getting Hotspot](#getting-hotspot)
Expand Down Expand Up @@ -46,98 +46,97 @@ performance data formats under this umbrella.

## Screenshots

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

### Visualize Data
### Visualizing Data

The main feature of hotspot is visualizing a `perf.data` file graphically.
The main feature of Hotspot is the graphical visualization of a `perf.data` file.

![hotspot summary page](screenshots/summary.png?raw=true "hotspot summary page")
![hotspot summary page](screenshots/summary.png?raw=true "Hotspot summary page")

![hotspot FlameGraph page](screenshots/flamegraph.png?raw=true "hotspot FlameGraph page")
![hotspot FlameGraph page](screenshots/flamegraph.png?raw=true "Hotspot FlameGraph page")

![hotspot off-CPU analysis](screenshots/off-cpu.png?raw=true "hotspot off-CPU analysis")
![hotspot off-CPU analysis](screenshots/off-cpu.png?raw=true "Hotspot off-CPU analysis")

![hotspot caller-callee page](screenshots/caller-callee.png?raw=true "hotspot caller-callee page")
![hotspot caller-callee page](screenshots/caller-callee.png?raw=true "Hotspot caller-callee page")

![hotspot bottom-up page](screenshots/bottom-up.png?raw=true "hotspot bottom-up page")
![hotspot bottom-up page](screenshots/bottom-up.png?raw=true "Hotspot bottom-up page")

![hotspot top-down page](screenshots/top-down.png?raw=true "hotspot top-down page")
![hotspot top-down page](screenshots/top-down.png?raw=true "Hotspot top-down page")

![hotspot dockwidget layouts](screenshots/dockwidgets.png?raw=true
"hotspot with custom dockwidget layout and disassembly view")
"Hotspot with custom dockwidget layout and disassembly view")

### Time Line

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

![hotspot timeline filtering by time](screenshots/timeline-filter-time.png?raw=true
"hotspot timeline filtering by time")
"Hotspot timeline filtering by time")

![hotspot timeline filtering by thread or process](screenshots/timeline-filter-thread.png?raw=true
"hotspot timeline filtering by thread or process")
"Hotspot timeline filtering by thread or process")

![hotspot timeline filtering applied to FlameGraph](screenshots/timeline-flamegraph.png?raw=true
"hotspot timeline filtering also applies to the data views on top, like e.g. the FlameGraph.
"Hotspot timeline filtering also applies to the data views on top, like e.g. the FlameGraph.
You can also zoom in on the timeline and inspect individual sample data.")

### Record Data

You can also launch `perf` from hotspot, to profile a newly started application
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](#recording-with-perf-without-super-user-rights) into account though.

![hotspot launch application](screenshots/record-launch.png?raw=true
"hotspot can launch a new application and profile it with perf from the record page.")
"Hotspot can launch a new application and profile it with perf from the record page.")

![hotspot attach to process](screenshots/record-attach.png?raw=true
"hotspot also allows runtime-attaching of perf to existing applications to profile them.")
"Hotspot also allows runtime-attaching of perf to existing applications to profile them.")

## Getting Hotspot

*Note: Hotspot is not yet packaged on all Linux distributions. In such cases, or when you want to use the
*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).
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
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).
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/).
Hotspot is available in Fedora (https://packages.fedoraproject.org/pkgs/hotspot/hotspot/).

### For any Linux distro: AppImage

Head over to our [list of AppImage build jobs][appimagejobs].
When you click on a job, you'll see a page with an "Artifacts" section that contains an "appimage" binary
you can then download. Unzip the AppImage file and make it executable, then run it.

[appimagejobs]: https://github.com/KDAB/hotspot/actions/workflows/build-appimage.yml?query=branch%3Amaster
You can either head over to the most [current release](https://github.com/KDAB/hotspot/releases/latest)
or the [continuous build](https://github.com/KDAB/hotspot/releases/tag/continuous).
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](http://appimage.org/).*
simply delete the downloaded file. Learn more about AppImage [here](https://appimage.org/).*

To find out how to debug the Appimage, see [HACKING](HACKING.md#debugging-the-appimage).
To find out how to debug the AppImage, see [HACKING](HACKING.md#debugging-the-appimage).

## 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](#getting-hotspot) from the distro
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](#getting-hotspot) from the distro
package manager or as an [AppImage](#for-any-linux-distro-appimage).

For everyone that wants to contribute to Hotspot or use the newest version without the Appimage detailed
For everyone that wants to contribute to Hotspot or use the newest version without the AppImage detailed
notes are found at [HACKING](HACKING.md#table-of-contents).

## Using
Expand All @@ -154,7 +153,7 @@ perf record --call-graph dwarf <your application>
[ 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.
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:
Expand All @@ -165,7 +164,7 @@ hotspot /path/to/perf.data

### Command Line options

Depending on your needs you may want to pass additional command line options to hotspot.
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](#import-export) for details on that).
Expand Down Expand Up @@ -221,7 +220,7 @@ and we only pay a price, when the process is actually getting switched out. Most
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
To do off-CPU analysis with Hotspot, you need to record the data with a very specific
command:

```bash
Expand All @@ -235,7 +234,7 @@ perf record \
<your application>
```

Alternatively, you can use the off-CPU check box in hotspot's integrated record page.
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
Expand All @@ -250,7 +249,7 @@ inbetween is often way more interesting to me - and that's what is shown to you
### 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
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:

Expand Down Expand Up @@ -304,22 +303,25 @@ 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,
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
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 currently only shows the name of the tracepoints in the timeline.

![hotspot tracepoints](screenshots/tracepoints.png?raw=true "hotspot tracepoints")
![hotspot tracepoints](screenshots/tracepoints.png?raw=true "Hotspot tracepoints")

### Disassembler

![hotspot disassembler page](screenshots/disassembler.png?raw=true "hotspot disassembler page")
![hotspot disassembler page](screenshots/disassembler.png?raw=true "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
Expand All @@ -345,7 +347,7 @@ to unwind the stack. This works quite well most of the time, but still can go wr
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
- 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
Expand All @@ -365,7 +367,7 @@ notably, unwinding will fail when:
- 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
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
Expand All @@ -377,15 +379,15 @@ notably, unwinding will fail when:

### debuginfod

hotspot supports downloading debug symbols via [debuginfod](https://sourceware.org/elfutils/Debuginfod.html).
This can be enabled by either adding download urls in the settings or launching hotspot with `DEBUGINFOD_URLS`
Hotspot supports downloading debug symbols via [debuginfod](https://sourceware.org/elfutils/Debuginfod.html).
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
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:
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
Expand All @@ -395,13 +397,13 @@ are _not_ available in hotspot currently:

### 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.
It is **not** a good idea to launch Hotspot with `sudo` or as `root` user. See e.g.
[Editing Files As Root](https://blog.martin-graesslin.com/blog/2017/02/editing-files-as-root/)
for an article on that matter. [Issue #83](https://github.com/KDAB/hotspot/issues/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:
when using Hotspot's record feature:

```text
You may not have permission to collect stats.
Expand All @@ -412,11 +414,11 @@ Consider tweaking /proc/sys/kernel/perf_event_paranoid:
2 - Disallow kernel profiling for unpriv
```

To workaround this limitation, hotspot can run perf itself with elevated privileges.
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
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](https://perfetto.dev/) or the [Mozilla profiler](https://profiler.firefox.com/) is
Expand All @@ -426,9 +428,9 @@ planned but not yet implemented. Patches welcome!

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](http://doc.qt.io/qtcreator/creator-cpu-usage-analyzer.html).
its integrated [CPU Usage Analyzer](https://doc.qt.io/qtcreator/creator-cpu-usage-analyzer.html).

## License

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

0 comments on commit 0131bbd

Please sign in to comment.