Add stats source for metrics from backup archives

This change adds a new type of stats source called BackupStatsFiles that
generates Prometheus metrics from backup archives via the cbmstatparser
utility that is included in the backup repository.

This use of Promtimer can be invoked with the --backup-archive-path
argument and starts Promtimer with a different out-of-the-box dashboard
built off these backup archive metrics.

Author: Lackshan

.gitignore

@@ -1,4 +1,5 @@
 *.iml
 *.iml~
+.vscode
 promtimer/__pycache__/
 .promtimer

README.md

@@ -17,15 +17,15 @@ interested in:
 ## Idea
 Promtimer:
 
-1. When running against cbcollects, starts a Prometheus server for each 
+1. When running against cbcollects, starts a Prometheus server for each
    cbcollect you are interested in exploring. (When run against a live
    cluster this step is not necessary.)
-1. Generates a convenient Grafana configuration with anonymous login, a 
+1. Generates a convenient Grafana configuration with anonymous login, a
    custom home dashboard, data sources and dashboards.
 1. Starts Grafana allowing you to login and browse dashboards that collect
    metrics from across each node in the cluster.
 1. Creates dashboard annotations based on important events that happened in
-   the cbcollect, taking information from the `diag.log` (or from an 
+   the cbcollect, taking information from the `diag.log` (or from an
    `events.log` file generated by the Event Logger) or from the `/logs` REST
    API.
 
@@ -45,9 +45,9 @@ For offline browsing of stats, you will additionally need:
 * (Optional) Event Logger from [cbmultimanager](https://github.com/couchbaselabs/cbmultimanager)
   if you wish to generate an `events.log` file
 
-If you happen to be building Couchbase Server 7.0 or later, you will already 
-have a Prometheus binary: it's in the `install/bin` directory of one of your 
-local builds. If you don't, the [Getting Started](https://prometheus.io/docs/introduction/first_steps/) 
+If you happen to be building Couchbase Server 7.0 or later, you will already
+have a Prometheus binary: it's in the `install/bin` directory of one of your
+local builds. If you don't, the [Getting Started](https://prometheus.io/docs/introduction/first_steps/)
 instructions on the Prometheus website are comprehensive. You don't actually
 need to install Prometheus, you just need the binary. [Downloading](https://prometheus.io/download/)
 and unzipping the pre-compiled binaries for your platform is sufficient.
@@ -56,7 +56,7 @@ If you're on Mac,`brew` is convenient:
 
     brew install prometheus
 
-It's also possible to build Prometheus from source yourself. This is 
+It's also possible to build Prometheus from source yourself. This is
 straightforward:
 
 ```
@@ -65,9 +65,9 @@ cd prometheus
 make prometheus
 ```
 
-You'll need a full Grafana install. The `grafana-server` binary alone isn't 
-sufficient as Grafana ships with many configuration files. 
-[Installation instructions](https://grafana.com/docs/grafana/latest/installation/) 
+You'll need a full Grafana install. The `grafana-server` binary alone isn't
+sufficient as Grafana ships with many configuration files.
+[Installation instructions](https://grafana.com/docs/grafana/latest/installation/)
 on the Grafana website look comprehensive. Follow the instructions for your
 platform to get a recent version of Grafana. On Mac, it's easy:
 
@@ -78,10 +78,16 @@ To get Promtimer, clone this repo locally:
     git clone https://github.com/couchbaselabs/promtimer.git
 
 As to cbcollects, you probably wouldn't be reading this if you didn't already
-have them. 
+have them.
 
-## How to Use Promtimer for Offline Analysis
+### cbbackupmgr stats files
+For visualisation of cbbackupmgr stats files, you'll also need access to the private
+`backup` repository in order to use the `cbmstatparser` utility. You'll need to
+either add the cbmstatparser binary to your path or manually specify it with the
+`--cbmstatparser-path` flag.
 
+## How to Use Promtimer for Offline Analysis
+### Visualising CBCollects
 Assemble the cbcollects in a directory. It's fine if you unzip them, but it's not
 necessary.
 
@@ -113,6 +119,27 @@ The Grafana dashboards page should open for you automatically. If not, navigate
 to `localhost:13300/dashboards` in your browser and begin exploring the
 available dashboards.
 
+### Visualising cbbackupmgr stats files
+Ensure that you have access to either a backup archive or a cbbackupmgr collect zip
+file.
+
+Start Promtimer:
+
+```bash
+promtimer --backup-archive-path <path-to-backup-archive-or-zip>
+```
+
+The above command assumes that `cbmstatparser` is available on your PATH. If it isn't,
+you'll need to specify the location of the `cbmstatparser` binary manually via the
+`--cbmstatparser-path` flag.
+
+The `path-to-backup-archive-or-zip` specifies the path to either a backup archive or to
+a cbbackupmgr collect zip file.
+
+The Grafana dashboards page should open for you automatically. If not, navigate
+to `localhost:13300/dashboards` in your browser and begin exploring the
+available dashboards.
+
 ## How to Use Promtimer for Online Monitoring
 
 Start Promtimer and provide the URL to the cluster and the name of the user that
@@ -130,8 +157,8 @@ the `/logs` REST API in the online case) and create dashboard annotations in Gra
 for important system events.
 
 As an option, Promtimer also supports the creating annotations based on an `events.log`
-file for system events generated by the Event Logger in the 
-[cbmultimanager](https://github.com/couchbaselabs/cbmultimanager) repository. Read 
+file for system events generated by the Event Logger in the
+[cbmultimanager](https://github.com/couchbaselabs/cbmultimanager) repository. Read
 [here](EVENTS.md) for more information on the Event Logger.
 
 ## Clean Up