neighbourhoodie-nnh-logo

Architecture Review Instructions

You have booked a CouchDB Architecture Review. These are the next steps:

  1. Please download and complete our CouchDB Questionnaire.
  2. Then download and run our Opservatory Agent, which will gather diagnostic data from your CouchDB instance.
  3. Via email to couchdb@neighbourhood.ie, submit the completed questionnaire and the results of the agent. You can also provide us with any CouchDB log files you have access to that have representative contents of a typical week or month, depending on log size. If you have experienced any particular issues, please include CouchDB logs around the time of the issue +/- 12 hours, if not longer.
  4. Our team of CouchDB experts will analyse the data and prepare a detailed report.

Note: this set of instructions is also available under a public URL, so you can easily share it.

The Opservatory Agent

The Opservatory Agent is a small piece of node.js software that runs on each of your CouchDB servers and collects raw analytics data from your CouchDB databases. It then compresses that analytics data and sends it back to Opservatory, where it is analysed and formatted into easy-to-read reports for you.

In order to work, the Opservatory Agent must be installed on a machine that can reach your CouchDB server(s). For best results, it should be run on the same server(s) that run CouchDB, local to each server. This means: for a 3 node cluster, run our agent 3 times.

The Opservatory Agent does not collect any actual data from your CouchDB. What it does gather is:

  • Database names
  • View documents
  • Database and document statistics (number of deleted documents, number of documents, etc)
  • Database configuration data
  • Some operating system statistics, such das disk space, max open connections etc.

It then stores these results as a gzipped JSON file on the local machine it is run on, so you can inspect the result. By following the instructions below, it will not automatically send the results off somewhere. You can inspect the JSON file and remove any info you do not want to share.

Finally, the tool is available in source form and you can inspect it, if you want.

The Opservatory Agent is written in node.js and includes this runtime in its binaries, so it doesn’t require any additional third-party installations.

Installation

To install, download the version of the tool built for your environment:

On Mac and Linux, make sure the downloaded binary can be executed: chmod +x opservatory-agent

Usage

To gather data on your installation, in the directory you put the Agent in, try running a collection (this won’t send anything anywhere, only create a gz file in that directory):

$ opservatory-agent once
  --couch-url http://admin:password@localhost:5984
  --node-name couchdb@localhost

once specifies that this is a one-off investigation that won’t transmit data to us, which is useful for getting a first impression of what the Agent does. Replace the value of the --couch-url parameter with the URL for your CouchDB instance, including admin credentials. In addition, provide the membership name of one of your CouchDB nodes for the second parameter.

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

$ opservatory-agent
Executing task 607 of 607 <========================================> 100%
Investigation completed in 8.34s.
Investigation results zipped and saved to /path/to/${md5(COUCH_URL)}.json.gz

At this point, you can inspect the Agent results and make sure that you’re not accidentally exposing any business secrets. For more options, run $ opservatory-agent -h.

Submitting your Data

Once you’ve completed the questionnaire, run the Agent and verified the payload, and found any log files pertinent to the analysis, please send everything to couchdb@neighbourhood.ie.

We’ll get back to you with a detailed report soon.