cstat 3.0.0

A visual stat tool for CrateDB clusters

=====
cstat
=====

*A visual stat tool for CrateDB clusters.*

``cstat`` is ispired by the awesome interactive process monitoring tool htop_.
``cstat`` should be a similar tool to iostat_, but for monitoring CrateDB_
clusters.

.. image:: screenshot.png
:scale: 100%
:alt: Screenshot of cstat in action

Requirements
============

``cstat`` requires **Python >= 3.6** and can connect to **CrateDB >= 2.3**.

Installation
============

``cstat`` is available from Pypi_ so you can install it using pip_.

::

pip install cstat

If you want to get the latest features and fixes, you can also install it
directly from Github_.

::

pip install git+https://github.com/chaudum/crate-top.git@master

Usage
=====

After installation you can monitor CrateDB running on localhost with default
configuration by invoking the following command::

>>> cstat --user crate

A full list of command line arguments are listed when invoking ``cstat`` with
the ``--help`` argument::

>>> cstat --help
usage: cstat [-h] [--host HOST] [--port PORT] [--interval INTERVAL]
[--user USER] [--version]

A visual stat tool for CrateDB clusters

optional arguments:
-h, --help show this help message and exit
--host HOST, --crate-host HOST
CrateDB host to connect to
--port PORT, --psql-port PORT
PSQL port of CrateDB host
--interval INTERVAL, --refresh-interval INTERVAL
amount of time in seconds between each update
--user USER, --db-user USER
database user
--version show program's version number and exit

By default ``cstat`` connects to ``localhost`` on port ``5432`` if not
otherwise specified.

Keyboard Shortcuts
==================

- ``0`` ... toggle cluster info
- ``1`` ... show utilization for CPU, process, memory, heap and disk
- ``2`` ... show I/O statistics for network and disk
- ``3`` ... show aggregated query duration based on jobs_log_
- ``x`` ... toggle nodes/aggregation view
- ``f3`` ... enable/disable job logging (this also sets the ``stats.jobs_log``
cluster setting)

Known Issues
============

- Small terminal sizes will raise CanvasErrors because of content overflow.

Todo
====

- [x] display disk usage
- [x] display disk i/o
- [x] display network i/o
- [x] display node names in detail views
- [x] use asyncio to perform http requests
- [x] coloring of i/o stats
- [ ] responsive i/o widget


.. _htop: http://hisham.hm/htop/
.. _iostat: http://linux.die.net/man/1/iostat
.. _CrateDB: https://crate.io
.. _aiopg: https://github.com/aio-libs/aiopg
.. _Pypi: https://pypi.org/project/cstat/
.. _pip: https://pypi.org/project/pip/
.. _Github: https://github.com/chaudum/crate-top
.. _jobs_log: https://crate.io/docs/reference/en/latest/configuration.html#collecting-stats


===================
Changelog for cstat
===================

Unreleased
==========

0.3.0
=====

Released on **2018/06/01** with the following changes:

- Make cstat compatible with CrateDB version 2.3.0 and greater.

- Updated process CPU usage calculation to work with CrateDB 2.3 and newer.

- Updated disk usage and disk i/o calculation to work with CrateDB 2.3 and
newer.

- Added ``-V`` (prompt for username) argument.

- Added ``--password`` and ``-W`` (prompt for password) arguments.

0.2.0
=====

Released on **2017/11/14** with the following changes:

- Implemented asynchronous database access using aiopg_ which uses the Postgres
Wire Protocol instead of the official CrateDB Python client which uses the
HTTP protocol.

- Added ``median``, ``percentile 95``, and ``percentile 99`` to query stats
table view.

- Added ``--user``/``--db-user`` command line argument to support user
authentication for clusters which run CrateDB 2.0 or greater.

- Changed the toggle key for enabling/disabling query stats from ``F1`` to
``F3``, because in the Terminator_ terminal the ``F1`` key is reserved for
"help".

- Pre-calculate used and idle CPU in SQL statement to avoid rounding issues
that can cause an display overflow in CPU widget.

.. _aiopg: https://github.com/aio-libs/aiopg
.. _Terminator: https://launchpad.net/terminator

0.1.0
=====

Initial release on **2017/03/30**: