Metadata-Version: 2.4
Name: pjlab-hstat
Version: 0.1.1
Summary: Cluster host monitor CLI.
Author: h-monitor maintainers
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# hstat

<p align="left">
  <a href="https://pypi.org/project/hstat/"><img alt="PyPI" src="https://img.shields.io/pypi/v/hstat?style=flat-square"></a>
  <a href="https://pypi.org/project/hstat/"><img alt="Python Version" src="https://img.shields.io/pypi/pyversions/hstat?style=flat-square"></a>
  <a href="#"><img alt="CI" src="https://img.shields.io/badge/CI-passing-brightgreen?style=flat-square"></a>
  <a href="#"><img alt="Code Style" src="https://img.shields.io/badge/code%20style-ruff-black?style=flat-square"></a>
</p>

Lightweight cluster resource monitor CLI.  
`hstat` helps you inspect CPU/MEM/GPU utilization by host or by user with a clear terminal table.

---

## Table of Contents

- [Screenshots](#screenshots)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [CLI Reference](#cli-reference)
- [Output Interpretation](#output-interpretation)

---

## Screenshots

### Query all
<a href="https://ibb.co/Zpxkn7fq"><img src="https://i.ibb.co/q3pPtVDT/query-all.png" alt="query-all" border="0"></a>

### Query by host
<a href="https://ibb.co/DPFmytmh"><img src="https://i.ibb.co/GfDGL0Gy/query-host.png" alt="query-host" border="0"></a>

### Query by user
<a href="https://ibb.co/JRNzWHwV"><img src="https://i.ibb.co/KjY9cWpd/query-user.png" alt="query-user" border="0"></a>

---

## Installation

### From source (recommended for now)

```bash
git clone <your-repo-url>
cd h-monitor
pip install .
```

### Editable mode (development)

```bash
pip install -e .
```

### Verify install

```bash
hstat --help
```

---

## Quick Start

### Query one host

```bash
hstat --host <hostname>
```

### Query one user

```bash
hstat --user <username> --range 1h
```

---

## CLI Reference

| Argument      | Alias                | Description                               | Default      |
| ------------- | -------------------- | ----------------------------------------- | ------------ |
| `--host`      | `-w`, `-n`, `--node` | Query by host/node                        | -            |
| `--user`      | `-u`                 | Query by user and auto-discover pods      | -            |
| `--tenant`    | -                    | Tenant label used in metrics query        | `ailab`      |
| `--namespace` | -                    | Namespace for `brainctl`/`rjob` lookup    | `ailab-ipec` |
| `--range`     | -                    | Prometheus range (e.g. `30m`, `1h`, `6h`) | `1h`         |

---

## Output Interpretation

- `UTL`: utilization meter, percentage-based load
- `MEM`: memory usage ratio against requested resources
- Row order: sorted by GPU utilization (high -> low)
- Footer `AVG`: average CPU/MEM/GPU usage across listed pods
