cstat 3.0.0
A visual stat tool for CrateDB clusters
License: Apache License 2.0

=====
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**: