ScyllaTop: a top like tool to view live scylladb metrics locally

What is ScyllaTop

ScyllaTop is a tool that enables you to log on to a machine running scylla, and view it's current state via metrics scylla defines. The purpose is to provide a top sort of functionality.

ScyllaTop depends on scylla reporting these metrics to collectd, a data gathering daemon. ScyllaTop then connects to collectd and presents its metrics to the user (hence it can be used, in fact, to also view non-scylla related metrics).

How to use ScyllaTop

Configuring collectd

First, you need a running collectd service. This collectd service must be configured to use the collectd unixsock plugin. In collectd's configuration file (on fedora: /etc/collectd.conf) uncomment the LoadPlugin line for unixsock so that it reads:

LoadPlugin unixsock

Later in the file you will find a commented-out configuration for this plugin. Uncomment it so that it looks something like this

<Plugin unixsock>
    SocketFile "/var/run/collectd-unixsock"
    SocketGroup "wheel"
    SocketPerms "0660"
    DeleteSocket false
</Plugin>

Of course, depending on your Linux installation, your configuration might be slightly different. Pay attention to the socket group and permissions - so that you have access to it when you run ScyllaTop. after this, restart collectd.

Make sure that network plugin is on by uncommenting:

LoadPlugin network

and setting its configuration to:

<Plugin network>
        Listen "127.0.0.1" "25826"
</Plugin>

Running ScyllaTop

Run ScyllaTop like so (here I assume you are in the directory where scylla is installed):

$ ./tools/scyllatop/scyllatop.py

With this command ScyllaTop will display a default selection of metrics relating to scylla.

You may, of course, specify the metrics you wish to view. You can use scyllatop.py -l to list the available metrics, which you can then specify on the command line. Metric specifications are like shell glob patterns, e.g. this will display all cpu-nice metrics:

$ ./tools/scyllatop/scyllatop.py '*cpu*nice*'

Troubleshooting

If something doens't work, have a look at the scyllatop.log file in your working directory, it might contain a clue.

Views

Currently, ScyllaTop supports two views. By default, it will aggregate metrics, displaying an average and a sum of a metric across CPUs. If you which to see individual metrics, hit S, for "simple view". You can return to the aggregate view by hitting M.

Other Options

ScyllaTop has quit a few more options to help you operate it. Run

$ ./tools/scyllatop/scyllatop.py --help

to see all of them.