From c9f8c98875ccc82dd769bff4e2a51a8034355375 Mon Sep 17 00:00:00 2001 From: Simone Rodigari Date: Mon, 20 Apr 2026 13:02:25 +0100 Subject: [PATCH 1/5] feat(hotspot): Add hotspot-bpf to retina shell --- shell/Dockerfile | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/shell/Dockerfile b/shell/Dockerfile index c885460ef2..07a1b101ef 100644 --- a/shell/Dockerfile +++ b/shell/Dockerfile @@ -74,4 +74,22 @@ RUN set -eux; \ rm /tmp/pwru.tar.gz; \ file /usr/local/bin/pwru | grep -q 'ELF' +# https://github.com/SRodi/hotspot-bpf/releases +ARG HOTSPOT_TAG="v0.1.0" +ENV HOTSPOT_TAG=${HOTSPOT_TAG} + +# Download and extract hotspot-bpf release (amd64 only for now) +RUN set -eux; \ + case "$ARCH" in \ + amd64|x86_64) HOTSPOT_ARCH="amd64" ;; \ + *) echo "Skipping hotspot-bpf: unsupported arch $ARCH" && exit 0 ;; \ + esac; \ + HOTSPOT_TAR="hotspot-bpf-linux-${HOTSPOT_ARCH}.tar.gz"; \ + curl -fL -o /tmp/hotspot.tar.gz "https://github.com/SRodi/hotspot-bpf/releases/download/${HOTSPOT_TAG}/${HOTSPOT_TAR}"; \ + tar -xz -C /usr/local/bin -f /tmp/hotspot.tar.gz "hotspot-bpf-linux-${HOTSPOT_ARCH}"; \ + mv "/usr/local/bin/hotspot-bpf-linux-${HOTSPOT_ARCH}" /usr/local/bin/hotspot; \ + chmod +x /usr/local/bin/hotspot; \ + rm /tmp/hotspot.tar.gz; \ + file /usr/local/bin/hotspot | grep -q 'ELF' + CMD ["/bin/bash", "-l"] From 190e6ffd3e279b3df6703bbaf72499317565560c Mon Sep 17 00:00:00 2001 From: Simone Rodigari Date: Tue, 21 Apr 2026 16:24:25 +0100 Subject: [PATCH 2/5] add SHA-256 checksum verification for hotspot-bpf download --- shell/Dockerfile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/shell/Dockerfile b/shell/Dockerfile index 07a1b101ef..a4ed62bd7b 100644 --- a/shell/Dockerfile +++ b/shell/Dockerfile @@ -86,10 +86,12 @@ RUN set -eux; \ esac; \ HOTSPOT_TAR="hotspot-bpf-linux-${HOTSPOT_ARCH}.tar.gz"; \ curl -fL -o /tmp/hotspot.tar.gz "https://github.com/SRodi/hotspot-bpf/releases/download/${HOTSPOT_TAG}/${HOTSPOT_TAR}"; \ + curl -fL -o /tmp/hotspot.tar.gz.sha256 "https://github.com/SRodi/hotspot-bpf/releases/download/${HOTSPOT_TAG}/${HOTSPOT_TAR}.sha256"; \ + cd /tmp && sha256sum -c hotspot.tar.gz.sha256; \ tar -xz -C /usr/local/bin -f /tmp/hotspot.tar.gz "hotspot-bpf-linux-${HOTSPOT_ARCH}"; \ mv "/usr/local/bin/hotspot-bpf-linux-${HOTSPOT_ARCH}" /usr/local/bin/hotspot; \ chmod +x /usr/local/bin/hotspot; \ - rm /tmp/hotspot.tar.gz; \ + rm /tmp/hotspot.tar.gz /tmp/hotspot.tar.gz.sha256; \ file /usr/local/bin/hotspot | grep -q 'ELF' CMD ["/bin/bash", "-l"] From 07695d56729a7d89f43653c2359c557f1d1e3445 Mon Sep 17 00:00:00 2001 From: Simone Rodigari Date: Tue, 21 Apr 2026 16:29:20 +0100 Subject: [PATCH 3/5] docs: add hotspot-bpf usage and custom thresholds to shell doc --- docs/06-Troubleshooting/shell.md | 40 +++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/docs/06-Troubleshooting/shell.md b/docs/06-Troubleshooting/shell.md index f0d12f355a..2163d6808c 100644 --- a/docs/06-Troubleshooting/shell.md +++ b/docs/06-Troubleshooting/shell.md @@ -4,7 +4,7 @@ The `retina shell` command allows you to start an interactive shell on a Kubernetes node or pod for adhoc debugging. -This runs a container image built from the Dockerfile in the `/shell` directory, with many common networking tools installed (`ping`, `curl`, etc.), as well as specialized tools such as [bpftool](#bpftool), [bpftrace](#bpftrace) [pwru](#pwru) or [Inspektor Gadget](#inspektor-gadget-ig). +This runs a container image built from the Dockerfile in the `/shell` directory, with many common networking tools installed (`ping`, `curl`, etc.), as well as specialized tools such as [bpftool](#bpftool), [bpftrace](#bpftrace), [pwru](#pwru), [hotspot-bpf](#hotspot-bpf), or [Inspektor Gadget](#inspektor-gadget-ig). Currently the Retina Shell only works in Linux environments. Windows support will be added in the future. @@ -286,6 +286,44 @@ ig -h ig run trace_dns:latest ``` +## [hotspot-bpf](https://github.com/SRodi/hotspot-bpf) + +eBPF performance lens for real-time root-cause diagnosis of Linux processes. hotspot-bpf correlates CPU time, scheduler contention, page-fault pressure, and RSS growth in a single terminal view, automatically classifying processes into diagnoses such as **CPU-bound**, **Starved**, **Noisy neighbor**, **Mem-thrashing**, or **OOM risk**. + +Requires the `SYS_ADMIN` and `PERFMON` capabilities (for eBPF program loading). + +```shell +kubectl retina shell --capabilities=SYS_ADMIN,PERFMON +``` + +You can then run for example: + +```shell +# Run with default settings (5s sampling window, top 10 processes) +hotspot -interval 5s -topk 5 + +# Filter by cgroup (useful for targeting specific pods) +hotspot -interval 5s -cgroup-filter +``` + +### Custom thresholds + +All diagnosis thresholds are configurable via a YAML config file. To generate the default configuration as a starting point: + +```shell +hotspot -generate-config > /tmp/thresholds.yaml +``` + +Edit the file to adjust thresholds for your environment, then pass it at runtime: + +```shell +hotspot -config /tmp/thresholds.yaml -interval 5s +``` + +Any value not specified in the file retains its compiled-in default. This is especially useful on **multi-core machines** where single-threaded workloads produce low system-wide CPU percentages — lowering the thresholds helps avoid missed classifications. + +For detailed information on all configurable parameters, see the [hotspot-bpf documentation](https://github.com/SRodi/hotspot-bpf#custom-thresholds). + ## [mpstat](https://www.man7.org/linux/man-pages/man1/mpstat.1.html) Tool for detailed reporting of processor-related statistics. `mpstat` is useful for network troubleshooting because it shows how much CPU time is spent handling SoftIRQs, which are often triggered by network traffic, helping identify interrupt bottlenecks or imbalanced CPU usage. SoftIRQs (Software Interrupt Requests) are a type of deferred interrupt handling mechanism in the Linux kernel used to process time-consuming tasks—like network packet handling or disk I/O—outside the immediate hardware interrupt context, allowing faster and more efficient interrupt processing without blocking the system. From 3685feae62c9a84ef4a28cd8bd5d974b83cba3b0 Mon Sep 17 00:00:00 2001 From: Simone Rodigari Date: Tue, 21 Apr 2026 16:31:10 +0100 Subject: [PATCH 4/5] use latest hotspot-bpf release --- shell/Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shell/Dockerfile b/shell/Dockerfile index a4ed62bd7b..7f9f8b196e 100644 --- a/shell/Dockerfile +++ b/shell/Dockerfile @@ -75,7 +75,7 @@ RUN set -eux; \ file /usr/local/bin/pwru | grep -q 'ELF' # https://github.com/SRodi/hotspot-bpf/releases -ARG HOTSPOT_TAG="v0.1.0" +ARG HOTSPOT_TAG="v0.1.1" ENV HOTSPOT_TAG=${HOTSPOT_TAG} # Download and extract hotspot-bpf release (amd64 only for now) From 3b21a019f46ea669bcb6ba4c4162c02a53855b00 Mon Sep 17 00:00:00 2001 From: Simone Rodigari Date: Tue, 21 Apr 2026 16:57:20 +0100 Subject: [PATCH 5/5] fix tarball name --- shell/Dockerfile | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/shell/Dockerfile b/shell/Dockerfile index 7f9f8b196e..2fa9d40cc8 100644 --- a/shell/Dockerfile +++ b/shell/Dockerfile @@ -85,13 +85,13 @@ RUN set -eux; \ *) echo "Skipping hotspot-bpf: unsupported arch $ARCH" && exit 0 ;; \ esac; \ HOTSPOT_TAR="hotspot-bpf-linux-${HOTSPOT_ARCH}.tar.gz"; \ - curl -fL -o /tmp/hotspot.tar.gz "https://github.com/SRodi/hotspot-bpf/releases/download/${HOTSPOT_TAG}/${HOTSPOT_TAR}"; \ - curl -fL -o /tmp/hotspot.tar.gz.sha256 "https://github.com/SRodi/hotspot-bpf/releases/download/${HOTSPOT_TAG}/${HOTSPOT_TAR}.sha256"; \ - cd /tmp && sha256sum -c hotspot.tar.gz.sha256; \ - tar -xz -C /usr/local/bin -f /tmp/hotspot.tar.gz "hotspot-bpf-linux-${HOTSPOT_ARCH}"; \ + curl -fL -o "/tmp/${HOTSPOT_TAR}" "https://github.com/SRodi/hotspot-bpf/releases/download/${HOTSPOT_TAG}/${HOTSPOT_TAR}"; \ + curl -fL -o "/tmp/${HOTSPOT_TAR}.sha256" "https://github.com/SRodi/hotspot-bpf/releases/download/${HOTSPOT_TAG}/${HOTSPOT_TAR}.sha256"; \ + cd /tmp && sha256sum -c "${HOTSPOT_TAR}.sha256"; \ + tar -xz -C /usr/local/bin -f "/tmp/${HOTSPOT_TAR}" "hotspot-bpf-linux-${HOTSPOT_ARCH}"; \ mv "/usr/local/bin/hotspot-bpf-linux-${HOTSPOT_ARCH}" /usr/local/bin/hotspot; \ chmod +x /usr/local/bin/hotspot; \ - rm /tmp/hotspot.tar.gz /tmp/hotspot.tar.gz.sha256; \ + rm "/tmp/${HOTSPOT_TAR}" "/tmp/${HOTSPOT_TAR}.sha256"; \ file /usr/local/bin/hotspot | grep -q 'ELF' CMD ["/bin/bash", "-l"]