Overview

Date: 2026-05-11

Time: 15:21

Overview

ftl2-htop is a distributed system monitoring TUI (terminal user interface) built on FTL2 that streams live CPU, memory, disk, network, and process metrics from remote hosts. It uses FTL2's gate event protocol to collect metrics via psutil on remote machines and renders them as a rich terminal dashboard using the rich library.

Key Concepts

• Distributed monitoring — monitors multiple remote hosts simultaneously from a single terminal
• Gate event protocol — FTL2's mechanism for streaming structured events (here SystemMetrics) back from remote hosts over SSH
• SystemMonitor — a gate-side component that collects host metrics using psutil at a configurable interval
• Rich Live rendering — uses rich.live.Live to display continuously updating panels, one per host
• No agent install required — only python3-psutil needs to be present on remote hosts; FTL2 handles the rest via SSH + gate
• Ansible-style inventory — reuses the same YAML inventory format as FTL2 (and Ansible), with ansiblehost and ansibleuser

Commands and Syntax

Installation of remote dependency:

dnf install python3-psutil   # Fedora/RHEL
apt install python3-psutil   # Debian/Ubuntu

Or via FTL2 itself:

await ftl.webservers.dnf(name="python3-psutil", state="present")

Running:

uvx --from "git+https://github.com/benthomasson/ftl2-htop" ftl2-htop -i inventory.yml
uv run ftl2_htop.py -i inventory.yml          # from local clone

Key flags:

| Flag | Effect |

|------|--------|

| -i inventory.yml | Specify inventory file (required) |

| -g webservers databases | Monitor specific groups only |

| --interval 1 | Set sampling interval in seconds |

| --no-processes | Skip process list (reduces bandwidth) |

| --debug | Print raw events instead of TUI |

Inventory format:

all:
  hosts:
    web-01:
      ansible_host: 192.168.1.10
      ansible_user: root

Relationships

• FTL2 gate protocol — ftl2-htop is a concrete example of consuming gate events (SystemMetrics) in a long-running streaming pattern, distinct from one-shot task execution
• Inventory — shares the same Ansible-style YAML inventory used by all FTL2 automation, including group targeting with -g
• Module system — psutil can be installed via FTL2's dnf module before monitoring, showing modules and event streaming composing together
• Gate modules — the SystemMonitor runs inside the gate process on each host, illustrating how gates can do more than execute tasks — they can run persistent collectors
• Event streaming — this is a primary real-world example of FTL2's event streaming capability (an advanced pattern area)

Exam-Relevant Points

• ftl2-htop demonstrates FTL2's event streaming architecture: gate processes on remote hosts emit structured events that the controller consumes in real time
• The data flow is: SSH connection → gate process → SystemMonitor (psutil) → SystemMetrics events → SSH channel → TUI rendering
• Only dependency on remote hosts is python3-psutil — FTL2's gate handles everything else
• Group filtering (-g) works the same way as in standard FTL2 task execution
• The --debug flag bypasses the TUI and prints raw events — useful for understanding the event protocol
• uvx allows running without local installation, demonstrating Python packaging with uv
• This tool exemplifies FTL2 being used beyond one-shot automation — as infrastructure for a persistent monitoring application