# check_couchdb

## Introduction

Check couchdb status.

### Requirements

* curl
* jq
* a running couchdb service
* authentication (see section Installation below)

## Syntax

```text
> check_couchdb -h
______________________________________________________________________

CHECK_COUCHDB
v0.7

(c) Institute for Medical Education - University of Bern
Licence: GNU GPL 3

https://os-docs.iml.unibe.ch/icinga-checks/Checks/check_couchdb.html
______________________________________________________________________

Show couchdb status.

SYNTAX:
check_couchdb [-h] [-t FILE] -m MODE

OPTIONS:
  -h or --help    show this help.
  -c CFGFILE      set a custom config file
                  default: /etc/icingaclient/.couchdb
  -m MODE         test a value; for debugging purposes the full json 
                  response will be shown

  MODE is one of
  httpd           Show counters for http request types
  httpd_methods   Show counters for http request methods
  open_databases  show number of open databases
  open_os_files   show number of file descriptors CouchDB has open
  replication     show last replication status
  pending         show count of pending updates for nodes, dbs and users
  replication     show last replication status
  up              show general couchdb health status

EXAMPLE:
check_couchdb -m up
  Check if couchdb is up and running

check_couchdb -m httpd_methods
  Show counters and change rate per sec of GET, POST, and other methods

check_couchdb -c /opt/couchdb/myconfig.sh -m up
  Source another config to define COUCH_URL

```

## Installation

The check script by default sources a file ``/etc/icingaclient/.couchdb``.
It is a shell script with read permissions for the icinga user.
It contains a line with the url to couchdb

```shell
# ls -l /etc/icingaclient/.couchdb
-r--------. 1 icingaclient icingaclient 110 Aug 29 09:53 /etc/icingaclient/.couchdb

# cat /etc/icingaclient/.couchdb
export COUCH_URL=http://USERNAME:PASSWORD@localhost:5984
```

The variable COUCH_URL will be used to request status information.

With parameter ``-c CFGFILE`` can define another location where to find the variable COUCH_URL.

## Checks

With the parameter ``-m METHOD`` you define what kind of check to perform.

### httpd

Show counters for http request types.

All values are taken from ``/_node/_local/_stats/couchdb/httpd``

``check_couchdb -m httpd_methods`` returns

```txt
OK: Couchdb :: Http request methods
______________________Property____Counter______Delta
              aborted_requests          0          0 per sec
                 bulk_requests          0          0 per sec
                      requests     190116          1 per sec
                 view_timeouts          0          0 per sec
                 find_timeouts          0          0 per sec
              explain_timeouts          0          0 per sec
             all_docs_timeouts          0          0 per sec
       partition_view_requests          0          0 per sec
       partition_find_requests          0          0 per sec
    partition_explain_requests          0          0 per sec
   partition_all_docs_requests          0          0 per sec
       partition_view_timeouts          0          0 per sec
       partition_find_timeouts          0          0 per sec
    partition_explain_timeouts          0          0 per sec
   partition_all_docs_timeouts          0          0 per sec
          temporary_view_reads          0          0 per sec
                    view_reads          0          0 per sec
    clients_requesting_changes          0          0 per sec
                purge_requests          0          0 per sec

 |abortedrequests=0;; bulkrequests=0;; requests=1;; viewtimeouts=0;; findtimeouts=0;; explaintimeouts=0;; alldocstimeouts=0;; partitionviewrequests=0;; partitionfindrequests=0;; partitionexplainrequests=0;; partitionalldocsrequests=0;; partitionviewtimeouts=0;; partitionfindtimeouts=0;; partitionexplaintimeouts=0;; partitionalldocstimeouts=0;; temporaryviewreads=0;; viewreads=0;; clientsrequestingchanges=0;; purgerequests=0;;
```

Description of the properties:

| Property                   | Description
|---                         | ---
| aborted_requests           | number of aborted requests
| bulk_requests              | number of bulk requests
| requests                   | number of HTTP requests
| view_timeouts              | number of HTTP view timeouts
| find_timeouts              | number of HTTP find timeouts
| explain_timeouts           | number of HTTP _explain timeouts
| all_docs_timeouts          | number of HTTP all_docs timeouts
| partition_view_requests    | number of partition HTTP view requests
| partition_find_requests    | number of partition HTTP _find requests
| partition_explain_requests | number of partition HTTP _explain requests
| partition_all_docs_requests| number of partition HTTP _all_docs requests
| partition_view_timeouts    | number of partition HTTP view timeouts
| partition_find_timeouts    | number of partition HTTP find timeouts
| partition_explain_timeouts | number of partition HTTP _explain timeouts
| partition_all_docs_timeouts|number of partition HTTP all_docs timeouts
| temporary_view_reads       | number of temporary view reads
view_reads                   | number of view reads
| clients_requesting_changes | number of clients for continuous _changes
| purge_requests             |number of purge requests

### httpd_methods

Show counters for http request methods.
All values are taken from ``/_node/_local/_stats/couchdb/httpd_request_methods``

``check_couchdb -m httpd_methods`` returns

```txt
OK: Couchdb :: Http request methods
____Method____Counter______Delta
      COPY          0          0 per sec
    DELETE          1          0 per sec
       GET     190332          1 per sec
      HEAD          0          0 per sec
   OPTIONS          0          0 per sec
      POST          0          0 per sec
       PUT          0          0 per sec
 |copy=0;; delete=0;; get=1;; head=0;; options=0;; post=0;; put=0;;
```

### httpd_status_codes

Show counters per http status code.
All values are taken from ``/_node/_local/_stats/couchdb/httpd_status_codes``

``check_couchdb -m httpd_status_codes`` returns

```txt
OK: Couchdb :: Http status codes
____Status____Counter______Delta
       200     199970          1 per sec
       201          0          0 per sec
       202          0          0 per sec
       204          0          0 per sec
       206          0          0 per sec
       301          0          0 per sec
       302          0          0 per sec
       304          0          0 per sec
       400          0          0 per sec
       401          2          0 per sec
       403          0          0 per sec
       404          9          0 per sec
       405          0          0 per sec
       406          0          0 per sec
       409          0          0 per sec
       412          0          0 per sec
       413          0          0 per sec
       414          0          0 per sec
       415          0          0 per sec
       416          0          0 per sec
       417          0          0 per sec
       500          0          0 per sec
       501          0          0 per sec
       503          0          0 per sec
 |http200=1;; http201=0;; http202=0;; http204=0;; http206=0;; http301=0;; http302=0;; http304=0;; http400=0;; http401=0;; http403=0;; http404=0;; http405=0;; http406=0;; http409=0;; http412=0;; http413=0;; http414=0;; http415=0;; http416=0;; http417=0;; http500=0;; http501=0;; http503=0;; 
```

### open_databases

Show number of open databases
The value is taken from ``/_node/_local/_stats/couchdb/open_databases``

This check sends performance data.

``check_couchdb -m open_databases`` returns

```txt
OK: Couchdb :: open_databases = 0
 |opendatabases=0;; 
```

### open_os_files

Show number of file descriptors CouchDB has open
The value is taken from ``/_node/_local/_stats/couchdb/open_os_files``

This check sends performance data.

``check_couchdb -m open_os_files`` returns

```txt
OK: Couchdb :: open_os_files = 0
 |openosfiles=0;; 
```

### pending

From url ``/up`` it fetches from seeds -> [node] -> pending_updates the values for

* _nodes
* _dbs
* _users

and summarizes its values.

It switches to warning if one of the values is > 0.

This check sends performance data.

``check_couchdb -m pending`` returns

```txt
OK: Couchdb :: pending updates: 0 (values below 'pending_updates' in /_up)
Reponse: of /_up
{
  "status": "ok",
  "seeds": {
    "couchdb@192.168.25.172": {
      "timestamp": "2023-08-28T07:27:54.938619Z",
      "last_replication_status": "ok",
      "pending_updates": {
        "_nodes": 0,
        "_dbs": 0,
        "_users": 0
      }
    },
    "couchdb@192.168.25.61": {}
  }
}
 |nodes=0;; dbs=0;; users=0;; 
```

### replication

From url ``/up`` it fetches seeds -> [node] -> last_replication_status.
It switches to critical if one of the seeds is not "ok".

``check_couchdb -m replication`` returns

```txt
OK: Couchdb :: replication (values 'last_replication_status' in /_up are 'ok')
Reponse: of /_up
{
  "status": "ok",
  "seeds": {
    "couchdb@192.168.25.172": {
      "timestamp": "2023-08-28T07:27:54.938619Z",
      "last_replication_status": "ok",
      "pending_updates": {
        "_nodes": 0,
        "_dbs": 0,
        "_users": 0
      }
    },
    "couchdb@192.168.25.61": {}
  }
}
```

### up

Simple check if couchdb is up and running.

From url ``/up`` it fetches the value status.
It switches to critical if one of the seeds is not "ok".

`check_couchdb -m up` returns

```txt
OK: Couchdb :: health status (value 'status' in /_up is 'ok')
Reponse of /_up: 
{
  "status": "ok",
  "seeds": {
    "couchdb@192.168.25.172": {
      "timestamp": "2023-08-28T07:27:54.938619Z",
      "last_replication_status": "ok",
      "pending_updates": {
        "_nodes": 0,
        "_dbs": 0,
        "_users": 0
      }
    },
    "couchdb@192.168.25.61": {}
  }
}

 ```