CouchDB Monitoring posted Tuesday, August 18, 2026 by The Neighbourhoodie Team CouchDBTipPerformance

We’ve written extensively about the lengths CouchDB goes to ensure your data is kept safe. CouchDB is incredibly reliable, but there are still a host of reasons to monitor your CouchDB metrics and statistics, from ensuring you’re ready to scale to learning where you can optimise for your use case and hardware right now.

In this post, we’ll take a deeper look into which CouchDB metrics and statistics to monitor. We’ll also introduce Opservatory 2.0, our CouchDB diagnostics tool that augments your metrics dashboard and helps you interpret and act on your results.

CouchDB Metrics and Statistics to Watch#

Simply put, “metrics” are the numbers that come out of CouchDB. A lot of the raw numbers you can get directly out of CouchDB by asking, like counts. “Statistics” are those metrics over time periods, like aggregates and medians.

To get started, grab your stats:

http://127.0.0.1:5984/_node/_local/_stats 

And if you want to dig even deeper:

http://127.0.0.1:5984/_node/_local/_system

Below are some things you absolutely want to keep an eye on from the results you’ll get.

Request Time, or Latency#

This is how long it takes CouchDB to return a response when queried. You should monitor this in every database, and in CouchDB it’s something you want to monitor for each node and will likely be your first indication when something starts going wrong.

It’s useful to know the min, max and median request times. The longer the time period you’re looking at, the less variance you should see. It’s also usual for request times to slowly increase over time as your database grows — think a median increase of 1ms per request over the space of a year if your setup supports you scaling well.

Any significant deviation in request time is a sign that something is seriously wrong. This makes request time a good overall pulse of your database health. It won’t, however, tell you what’s wrong — to diagnose issues, you’ll need to dig a little deeper or use Opservatory.

Internal Replication Jobs#

CouchDB is known and loved for its custom replication protocol and there’s a good chance it’s among the reasons you chose to work with CouchDB. But even if you don’t, a CouchDB cluster uses replication internally.

This is a cluster-wide number that lets you know if all the nodes in your cluster are on the same page, which they need to be. If they aren’t, an internal replication job is started to bring them to converge and this number goes up in whole integers (1, 2, 3…).

Big spike? Houston, we have a problem with at least one node. Number of jobs not converging on 0? Things are probably critical.

Number of Open Databases#

Because CouchDB supports database-per-user and time-series database creation so well, it’s not unusual to open several hundred databases at once. Not unusual for any database, in CouchDB opening and closing a database is an expensive operation and the performance costs can add up.

By default, the maximum number of open databases is 500. This is CouchDB’s built-in overload protection and it’s an arbitrary number you can change if and when needed. Keeping an eye on how many open databases you have at any one time — especially during peak request times for your organisation or application — will have implications for your database deletion strategies. So having a good handle on actual behaviour will help you develop a strategy for your use case that serves you best.

Message Queues#

CouchDB is written in Erlang, and Erlang processes — which are distinct from operating system processes — communicate with each other using messages. Each process has a message inbox or queue. You can request the message_queues object to get a list of CouchDB modules and their associated message queue lengths to get a deeper peek into what your CouchDB is getting up to.

Longer queues indicate more concurrent work is going on. This is one metric that’s particularly helpful to see on a graph. Some queues may be of more interest, for example if the couch_replication queue is getting backed up, it means shard replicas may be drifting out of sync across the cluster.

A Brief Aside on CouchDB Benchmarks#

We’ve said it before and we’ll say it again:

| All software benchmarks and claims of performance are carefully crafted lies…

There is no magic 3-step way to achieve better performance because every situation, setup and set of demands differs from the next and the last. Choices are also composed of trade-offs. Let’s take the example of another NoSQL database CouchDB is often compared to: MongoDB is fast at the expense of reliability; additional plugins or careful architecting are needed to get near the data reliability CouchDB is known for right out-of-the-box.

Because every situation is different, our team created a diagnostics tool called Opservatory to help you get the best performance for your setup. We’ll get back to that in a sec, but if you would like expert help benchmarking your system and uncovering bottlenecks, give us a call. We also offer professional CouchDB Training to help you get to know the inner workings of CouchDB and its metrics even better.

Using Your Metrics to Make Deductions#

There’s no shortage of tools designed to help create your own metrics dashboard: Datadog has a dedicated article to get your CouchDB dashboard up-and-running (but you’ll have to forgive the outdated CouchDB logo!). Plus there are many open source tools like Grafana or Prometheus to help you get a live metrics overview.

But knowing what to do with all those numbers once you have them is another thing altogether…

Introducing Opservatory 2.0#

If you’re new to CouchDB, how do you know if numbers represent a healthy database when you first get set up? When high-level numbers spike or sink, where do you look next to make a diagnosis? That’s exactly why we built Opservatory. And the base version is completely free to use!

Opservatory is a diagnostics tool that monitors your CouchDB 24/7 and lets you know what action you can take when it finds room for improvement, or, in the worst case, when numbers go haywire. It’s a complement to a monitoring tool that trains you and your team how to chase down and fix problems and tailor CouchDB for your use-case, based on our 12+ years of experience professionally supporting CouchDB for some of the largest companies in the world and contributing to the CouchDB projects itself. We’ve just finished overhauling it to make it even more comprehensive and user friendly, hence 2.0.

How Opservatory Helps#

Opservatory performs hundreds of regular checks to make sure your CouchDB is healthy and optimised for both your use-case configuration and your hardware. It then packages its findings into reports so you can easily observe and navigate changes between time periods. You get to choose how regularly you receive these.

Here’s a small selection of some of the things it can tell you:

• How to optimise your Views for performance
• When you’re soon going to encounter the limit of databases open at one time
• If your replication settings can be changed for better performance
• If your disk space usage could use attention before problems arise
• If you could change your sharding parameters to better suit your use case
• Whether your Design Docs could be improved
• and many, many more!

Check out our release announcement to learn how 2.0 introduces enhancements, and visit the Opservatory website to get started. The base version is free forever.

We hope to greet you from your Opservatory viewing deck soon. Happy monitoring!