Skip to content
qtopPublic

About

qtop (pronounced queue-top) is a tool written in order to monitor the state of Workload Managers, **SLURM, PBS, SGE & OAR** families, along with related information relevant on HPC & related clusters. It supports >10000s of nodes or cores. It is the evolution of the historic shell version of the tool, born out of CERN's LHC project needs...

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

53 stars

Watchers

3 watching

Forks

Latest commit

 

History

1,699 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

qtop

build-qtop CodeQL status Coverage checks License: MIT Python 3 OpenSSF Scorecard Security Insights metadata OpenSSF Best Practices

qtop is a scheduler-independent observability layer for HPC clusters, with an extremely fast terminal interface. It is a portable, dependency-light cluster observability and scheduler debugging tool for Slurm, PBS, SGE and OAR - and even more, with your contributed plugin effort.

See your whole cluster in one terminal. Capture it. Replay it. Compare it.

qtop terminal demo

Why qtop?

Schedulers expose a great deal of information, but their native commands rarely provide one concise view of jobs, queues, nodes, states and core occupancy. qtop turns scheduler output into a consistent terminal dashboard that is useful during daily operations and incident analysis.

  • See cluster utilization, queues, users, node states and per-core job placement.
  • Use the same interface across Slurm, PBS/Torque, SGE and OAR.
  • Filter, sort, highlight, transpose and navigate large worker-node matrices interactively.
  • Capture scheduler output for bug reports or offline investigation.
  • Replay recent frames to understand scheduling changes over time.
  • Export normalized cluster data as JSON.
  • Run without a resident service, database, or heavy runtime dependency stack.

Quick start

See the Quickstart guide for a short walkthrough from the demo to live monitoring, saved traces and support snapshots.

Clone the repository and launch the built-in demo:

git clone https://github.com/qtop/qtop.git
cd qtop
./qtop -b demo -FGTw

On a scheduler host, qtop can normally discover the available scheduler:

./qtop -w

Select it explicitly when needed:

./qtop -b slurm -w
./qtop -b slurm_json -w
./qtop --slurm-summary -w
./qtop -b pbs -w
./qtop -b sge -w
./qtop -b oar -w

The optional value after -w is the refresh interval in seconds. For example, -w 10 refreshes every ten seconds; without a value, watch mode refreshes every two seconds.

Run ./qtop --help for the complete command-line reference. While watch mode is active, press ? for the interactive key map.

Installation

From source

git clone https://github.com/qtop/qtop.git
cd qtop
./qtop --version

To install a checkout instead of running it directly, use a virtual environment and python -m pip install .. Python 3.6-3.8 use a legacy-compatible build backend; modern Python uses the metadata in pyproject.toml.

From PyPI

python3 -m pip install --user qtop
$HOME/.local/bin/qtop --version

PyPI currently serves qtop's legacy 2016 release. Until the next release is published, install from source for current Slurm support and recent fixes. A system-wide or virtual-environment installation can omit --user.

Capture, inspect and replay

Read scheduler traces from a directory instead of invoking live commands:

./qtop -b slurm -s /path/to/slurm-traces

Create a support sample containing qtop output, logs and scheduler traces (use -L -A for a reproducible anonymized state snapshot):

./qtop -L

Reproduce an anonymized support archive with qtop --load-sample archive.tar. This restores parsed state and presentation without contacting the scheduler.

Replay automatically captured frames from a specific time:

./qtop -R 1823

Export the normalized cluster state to a JSON file in the configured save directory:

./qtop -E

-E keeps the terminal view on stdout. See the capture and export guide for filenames, a real JSON example, archive contents and anonymization limits.

See the full documentation for trace filenames, configuration, filtering, replay formats, anonymization and scheduler-specific notes.

How it works

qtop separates scheduler-specific collection and parsing from a common cluster-state model and terminal presentation:

  1. A scheduler plugin collects live command output or reads saved traces.
  2. The plugin normalizes jobs, nodes and queues into a shared cluster state.
  3. qtop renders that state in a fast terminal view or exports it for other tools.

This design keeps the core scheduler-independent and makes support for another batch system a bounded plugin contribution.

See the architecture diagram and source map for the module relationships and the paths through collection, rendering, capture and replay.

Compatibility

qtop targets Python 3 and Linux-based HPC environments. Its CI matrix covers modern Python versions and retains a dependency-light compatibility lane for older enterprise distributions commonly found on clusters.

Terminal monitoring is the primary interface.

Maintainers and contributors can run make ci-deps once and make pre-pr in a Linux x86-64 CPython 3.12 virtual environment to reproduce the local PR gates, including coverage, type checks and both parser fuzzers. See CONTRIBUTING.md for other platforms and Python 3.6 checks.

Documentation and community

Bug reports with captured scheduler samples are especially valuable. New scheduler plugins, sample fixtures, documentation improvements and portability fixes are welcome.

AUTHORS: Original Bash version by Fotis Georgatos. Python port by Sotiris Fragkiskos. Additional authors: Evangelos Papadopoulos (push for 1.0) and Nicola Trozzi (admitted slurm support).

Full contributor credits: GitHub contributors.

License: MIT.

About

qtop (pronounced queue-top) is a tool written in order to monitor the state of Workload Managers, **SLURM, PBS, SGE & OAR** families, along with related information relevant on HPC & related clusters. It supports >10000s of nodes or cores. It is the evolution of the historic shell version of the tool, born out of CERN's LHC project needs...

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

53 stars

Watchers

3 watching

Forks

Releases

Packages

Used by

Contributors

Languages