couchdb-stat-collector

couchdb-stat-collector

A CLI tool for collecting statistics about a CouchDB node or cluster.

This project is a work in progress. Its interface may change as new features are added.

Usage

You can get this tool via NPM:

$ npm i -g couchdb-stat-collector

Now the couchdb-stat-collector command should be on your $PATH. Try it like this:

$ couchdb-stat-collector http://admin:password@localhost:5984

Replace the first positional parameter with the URL for your CouchDB instance, including admin credentials. Alternatively, you can set the COUCH_URL environment variable with the correct URL.

Once completed, it should give you a success message like this:

$ couchdb-stat-collector
Investigation results zipped and saved to /path/to/${md5(COUCH_URL)}.json.gz

You can also post an investigation to the URL of an analyser service using an access token, like this:

$ couchdb-stat-collector \
	--service \
	--service-url https://example.com\
	--service-token ...
Investigation results posted to https://example.com

For more usage information, run couchdb-stat-collector --help.

Task Files

The collector uses a "task file" to conduct its investigation. By default, it uses tasks.json in the project's root directory. It is a JSON file containing an array where each element is an object representing a task for the collector to execute.

Tasks have these recognizes properties:

• access: a jq filter, which is used to parse results into arguments used to template route and name. This PR currently relies on node-jq to facilitate this parsing, but that project has a number of security vulnerabilities that do not appear likely to be resolved soon.
• after: an array of other task objects to run after this one. Arguments parsed with access from the task's results are merged with the task's own arguments and passed to these sub-tasks.
• name: a friendly identifier for the task. Defaults to the task's route, and so is useful when that information may not reliably indicate the task's nature or purpose. In the example, one task uses the name {{db}}/_design_docs to indicate that it retrieves all of that database's design documents. Like route, this property is templated using mustache.
• query: an object whose properties are converted into a querystring and used in the task's request.
• route: a URL fragment indicating the path of the task's request. Like name, this property is templated using mustache.
• save: a boolean flag for whether or not the result of a task should be saved. Useful for running tasks solely to populate their sub-tasks.
• version: a semver version identifier that is tested against a version argument (if it is present) which should be acquired by querying the cluster's root endpoint (/). There is an example of this in the test suite under "should do version checking".

For an example, check the collector's default task file.

Development & Testing

Get and build the tool locally with Git:

$ git clone neighbourhoodie/couchdb-stat-collector
$ cd couchdb-stat-collector
$ npm install

Now you can run the test suite like this:

$ npm test

You can run the tool like this:

$ npm start

License

Proprietary. Use only with permission of Neighbourhoodie Software GmbH.