> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/integrations/sources/couchdb.md).

# CouchDB

The CouchDB source collects metrics and logs from Apache CouchDB. Metrics are scraped from the CouchDB server over HTTP or HTTPS using a monitoring user, covering request timing, database operations, open file descriptors, and HTTP activity. Logs are read from CouchDB's log file(s) on the collector host and optionally parsed into structured fields.

### Supported Telemetry

| Platform | Metrics | Logs | Traces |
| -------- | ------- | ---- | ------ |
| macOS    | ✓       | ✓    |        |
| Linux    | ✓       | ✓    |        |
| Windows  | ✓       | ✓    |        |

### Prerequisites

Metrics:

* A reachable CouchDB server and the TCP port it listens on (default `5984`).
* A CouchDB user with permission to read the server statistics endpoint (`/_node/{node-name}/_stats`). Use a least-privilege monitoring account rather than an administrative one.
* Network reachability from the collector host to the CouchDB port.
* If TLS is enabled, the certificate authority file and, for mutual TLS, the client certificate and private key files available on the collector host.

Logs:

* CouchDB writing its log file(s) on a host the collector can read.
* The log file path(s). The default is `/var/log/couchdb/couchdb.log`.
* Read access for the collector to those file(s).

CouchDB exposes statistics through its server API. See the [CouchDB Server API reference](https://docs.couchdb.org/en/stable/api/server/common.html) for the `/_node/{node-name}/_stats` monitoring endpoint.

### Configuration

<figure><img src="/files/1PKdNrVPKFDLvf0drUUW" alt="Bindplane docs - CouchDB - image 1"><figcaption></figcaption></figure>

**Telemetry Type**

| Parameter             | Type                | Required | Default               | Description                                                        |
| --------------------- | ------------------- | -------- | --------------------- | ------------------------------------------------------------------ |
| Choose Telemetry Type | Enum: Logs, Metrics | No       | `["Logs", "Metrics"]` | Which signals this source collects. Select Logs, Metrics, or both. |

**Logs**

| Parameter | Type                 | Required | Default                        | Description                                                                             |
| --------- | -------------------- | -------- | ------------------------------ | --------------------------------------------------------------------------------------- |
| Log Paths | Strings              | No       | `/var/log/couchdb/couchdb.log` | Path to CouchDB log file(s). Relevant when Logs is selected. Advanced.                  |
| Start At  | Enum: beginning, end | No       | `end`                          | Start reading logs from `beginning` or `end`. Relevant when Logs is selected. Advanced. |
| Parse     | Boolean              | No       | `true`                         | Parse the log fields into structured data. Relevant when Logs is selected. Advanced.    |

**Metrics**

| Parameter | Type    | Required | Default   | Description                                                                          |
| --------- | ------- | -------- | --------- | ------------------------------------------------------------------------------------ |
| Hostname  | String  | Yes      | *(empty)* | The hostname or IP address of the CouchDB system. Relevant when Metrics is selected. |
| Port      | Integer | No       | `5984`    | The TCP port of the CouchDB system. Relevant when Metrics is selected.               |
| Username  | String  | Yes      | *(empty)* | The username to use when connecting to CouchDB. Relevant when Metrics is selected.   |
| Password  | String  | Yes      | *(empty)* | The password to use when connecting to CouchDB. Relevant when Metrics is selected.   |

**Advanced**

| Parameter                           | Type    | Required | Default   | Description                                                                                                                                                                                                |
| ----------------------------------- | ------- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Collection Interval                 | Integer | No       | `60`      | How often (seconds) to scrape for metrics. Relevant when Metrics is selected.                                                                                                                              |
| Enable TLS                          | Boolean | No       | `false`   | Whether to use TLS when connecting to CouchDB. Relevant when Metrics is selected.                                                                                                                          |
| Strict TLS Certificate Verification | Boolean | No       | `false`   | Require TLS certificate verification. Relevant when Enable TLS is true and Metrics is selected.                                                                                                            |
| TLS Certificate Authority File      | String  | No       | *(empty)* | Certificate authority used to validate TLS certificates. Relevant when Enable TLS and Strict TLS Certificate Verification are true and Metrics is selected.                                                |
| Mutual TLS Authentication           | Boolean | No       | `false`   | Require TLS mutual authentication. Relevant when Enable TLS and Strict TLS Certificate Verification are true and Metrics is selected.                                                                      |
| TLS Client Certificate File         | String  | Yes      | *(empty)* | A TLS certificate used for client authentication, if mutual TLS is enabled. Relevant when Enable TLS, Strict TLS Certificate Verification, and Mutual TLS Authentication are true and Metrics is selected. |
| TLS Client Private Key File         | String  | Yes      | *(empty)* | A TLS private key used for client authentication, if mutual TLS is enabled. Relevant when Enable TLS, Strict TLS Certificate Verification, and Mutual TLS Authentication are true and Metrics is selected. |
| Metrics                             | Metrics | No       | *(empty)* | Toggle the individual CouchDB metrics you wish to collect on and off. Relevant when Metrics is selected.                                                                                                   |

### Examples

#### Collect metrics and logs from a local CouchDB instance

Scrape metrics from CouchDB on the default port with a monitoring user and tail the default log file.

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  name: couchdb
spec:
  type: couchdb
  parameters:
    - name: telemetry_types
      value: ["Logs", "Metrics"]
    - name: hostname
      value: localhost
    - name: port
      value: 5984
    - name: username
      value: monitoring
    - name: password
      value: "(redacted)"
    - name: log_paths
      value:
        - /var/log/couchdb/couchdb.log
```

#### Metrics only over TLS

Connect to CouchDB over HTTPS with certificate verification using a custom CA file.

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  name: couchdb-tls
spec:
  type: couchdb
  parameters:
    - name: telemetry_types
      value: ["Metrics"]
    - name: hostname
      value: couchdb.internal
    - name: port
      value: 6984
    - name: username
      value: monitoring
    - name: password
      value: "(redacted)"
    - name: enable_tls
      value: true
    - name: strict_tls_verify
      value: true
    - name: ca_file
      value: /opt/tls/couchdb-ca.crt
```

### Configuration Tips

* Use a dedicated least-privilege CouchDB user for monitoring rather than an admin account. The source only needs read access to the statistics endpoint.
* When TLS is enabled but Strict TLS Certificate Verification is left off, certificate verification is skipped (`insecure_skip_verify`). Enable strict verification and supply a CA file for production.
* The Metrics parameter lets you disable individual CouchDB metrics you do not need, reducing volume.

### Troubleshooting

#### Connection refused

Symptoms: the receiver cannot reach CouchDB and metrics never arrive.

Solutions:

1. Confirm the Hostname and Port match the CouchDB listener (default `5984`, or `6984` for HTTPS).
2. Verify a firewall or security group is not blocking the collector host from the CouchDB port.

#### Authentication failed

Symptoms: scrape errors referencing unauthorized or 401 responses.

Solutions:

1. Confirm the Username and Password are correct and the account can read `/_node/{node-name}/_stats`.
2. Confirm the monitoring user exists in CouchDB and is enabled.

#### TLS handshake failure

Symptoms: scrape errors referencing certificate or TLS handshake problems when Enable TLS is on.

Solutions:

1. With Strict TLS Certificate Verification on, supply a TLS Certificate Authority File that signs the CouchDB server certificate.
2. For mutual TLS, confirm the client certificate and private key files are present and readable on the collector host.

#### No logs collected

Symptoms: metrics arrive but no log records appear.

Solutions:

1. Confirm the Log Paths point at files CouchDB is actually writing.
2. Confirm the collector process has read access to those files. Set Start At to `beginning` to read existing content.

### Standalone Source

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  name: couchdb
spec:
  type: couchdb
  parameters:
    - name: telemetry_types
      value: ["Logs", "Metrics"]
    - name: hostname
      value: 127.0.0.1
    - name: port
      value: 5984
    - name: username
      value: monitoring
    - name: password
      value: "(redacted)"
    - name: collection_interval
      value: 60
    - name: enable_tls
      value: false
    - name: log_paths
      value:
        - /var/log/couchdb/couchdb.log
    - name: start_at
      value: end
    - name: parse
      value: true
```

### Related Resources

* [CouchDB Server API reference — statistics and monitoring endpoints](https://docs.couchdb.org/en/stable/api/server/common.html)
* [OpenTelemetry CouchDB receiver (`couchdbreceiver`)](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/couchdbreceiver)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bindplane.com/integrations/sources/couchdb.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.