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 Types

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 for the /_node/{node-name}/_stats monitoring endpoint.

Configuration

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.

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.

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

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
• OpenTelemetry CouchDB receiver (couchdbreceiver)