Couchbase monitoring integration

Our Couchbase integration collects and sends inventory and metric data from your Couchbase cluster to the New Relic platform, where you can quickly see the health of your Couchbase environment. We collect data at the cluster, node, query engine, and bucket level so you can trace a problem to its source.

Read on to install the integration, and to see what data we collect.

Compatibility and requirements

Our integration is compatible with Couchbase version 4.0 or higher.

Quick start

If you're not running Couchbase in Kubernetes or ECS environments, we recommend our guided install. Our guided install uses our infrastructure agent and our CLI to set up the Couchbase integration, and discovers other applications and log sources running in your environment and then recommends which ones you should instrument.

The guided install works with most setups. But if it doesn't suit your needs, there are other install options below.

Ready to get started? Click the relevant button, depending on which data center region you use. When you're done with the install, return to this documentation to review the configuration options.

Guided install, US region

Guided install, EU region

Install

To install the Couchbase integration, follow the instructions for your environment:

Install the infrastructure agent, and replace the INTEGRATION_FILE_NAME variable with nri-couchbase.
Change directory to the integrations folder:
```
cd /etc/newrelic-infra/integrations.d
```

Copy of the sample configuration file:

sudo cp couchbase-config.yml.sample couchbase-config.yml

Edit the couchbase-config.yml file as described in the configuration settings.

Download the nri-couchbase .MSI installer image from:
https://download.newrelic.com/infrastructure_agent/windows/integrations/nri-couchbase/nri-couchbase-amd64.msi
To install from the Windows command prompt, run:
```
msiexec.exe /qn /i PATH\TO\nri-couchbase-amd64.msi
```
In the Integrations directory, C:\Program Files\New Relic\newrelic-infra\integrations.d\, create a copy of the sample configuration file by running:
```
cp couchbase-config.yml.sample couchbase-config.yml
```
Edit the couchbase-config.yml file as described in the configuration settings.

Update your integration

This integration doesn't automatically update. For best results, regularly update the integration package and the infrastructure agent.

Post-installation tasks

When you're done with the install, you can set configuration options. Some configurations are required to get the integration to work, while some are optional.

Configure the integration

If you enabled this integration via our ECS or Kubernetes integration, see those docs:

For the standard on-host installation, this integration comes with a YAML config file, apache-config.yml. This configuration is where you can place required login credentials and configure how data is collected. Which options you change depends on your setup and preferences. It comes with a sample config file apache-config.yml.sample that you can copy and edit.

The configuration file has common settings applicable to all integrations, such as interval, timeout, inventory_source. To read all about these common settings, refer to our Configuration Format document.

Specific settings related to Couchbase are defined using the env section of the configuration file. These settings control the connection to your Couchbase instance as well as other security settings and features. The list of valid settings is described in the next section of this document.

Couchbase configuration options

The Couchbase integration collects both metrics and inventory information. This table shows what each configuration option applies to.

Setting	Description	Default	Applies to
HOSTNAME	Hostname or IP where Couchbase is running.	localhost	M/I
PORT	Port on which Couchbase API is listening.	8091	M/I
QUERY_PORT	Port on which Couchbase N1QL service is listening.	8093	M/I
USERNAME	Username for accessing Couchbase API.	N/A	M/I
PASSWORD	Password for the given user.	N/A	M/I
USE_SSL	Use SSL when communicating with the Couchbase.	false	M/I
CA_BUNDLE_FILE	Location of SSL certificate on the host. Only required if `USE_SSL` is true.	N/A	M/I
CA_BUNDLE_DIR	Alternative Certificate Authority bundle directory.	N/A	M/I
TIMEOUT	Timeout for API requests, in seconds.	30	M/I
ENABLE_BUCKETS	If true, collects bucket resources.	true	M
ENABLE_BUCKET_STATS	If true, collects additional bucket statistics.	true	M
ENABLE_CLUSTER_AND_NODES	If true, collects cluster and node resources.	true	M
METRICS	Set to `true` to enable metrics-only collection.	false
INVENTORY	Set to `true` to enable inventory-only collection.	false

The values for these settings can be defined in several ways:

Adding the value directly in the config file (the most common way).
Replacing the values from environment variables using the {{}} notation. This requires infrastructure agent version 1.14.0 or higher. For more information, see Infrastructure configuration or see the environment variable example.
Using secrets management. Use this to protect sensitive information, such as passwords that would be exposed in plain text in the configuration file. For more information, see Secrets management.

Labels

You can further decorate your metrics using labels. Labels allow you to add attributes (key/value pairs) to your metrics, which you can then use to query, filter, or group your metrics.

Our default sample config file includes examples of labels but, because they're not mandatory, you can remove, modify, or add new ones of your choice.

labels:
   env: production
   role: load_balancer

Example configurations

This is the basic configuration used to collect metrics and inventory from your localhost:

integrations:
  - name: nri-couchbase
    env:
      HOSTNAME: localhost
      PORT: 8091
      QUERY_PORT: 8093
      USERNAME: couchbase_user
      PASSWORD: couchbase_password
    interval: 15s
    labels:
      environment: production
    inventory_source: config/couchbase

This configuration collects metrics every 15 seconds and inventory every 60 seconds:

integrations:
  - name: nri-couchbase
    env:
      METRICS: true
      HOSTNAME: localhost
      PORT: 8091
      QUERY_PORT: 8093
      USERNAME: couchbase_user
      PASSWORD: couchbase_password
    interval: 15s
    labels:
      environment: production

  - name: nri-couchbase
    env:
      INVENTORY: true
      HOSTNAME: localhost
      PORT: 8091
      QUERY_PORT: 8093
      USERNAME: couchbase_user
      PASSWORD: couchbase_password
    interval: 60s
    labels:
      environment: production
    inventory_source: config/couchbase

In this configuration we are using the environment variable COUCHBASE_HOST to populate the HOSTNAME setting of the integration:

integrations:
  - name: nri-couchbase
    env:
      METRICS: "true"
      HOSTNAME: {{COUCHBASE_HOST}}
      PORT: 8091
      QUERY_PORT: 8093
      USERNAME: couchbase_user
      PASSWORD: couchbase_password
    interval: 15s
    labels:
      env: production
      role: load_balancer

In this configuration we are monitoring multiple Couchbase servers from the same integration. For the first instance (HOSTNAME: 1st_couchbase_host) we are collecting metrics and inventory while for the second instance (HOSTNAME: 2nd_couchbase_host) we will only collect metrics.

integrations:
  - name: nri-couchbase
    env:
      METRICS: "true"
      HOSTNAME: 1st_couchbase_host
      PORT: 8091
      QUERY_PORT: 8093
      USERNAME: couchbase_user
      PASSWORD: couchbase_password
    interval: 15s
    labels:
      env: production
      role: load_balancer
  - name: nri-couchbase
    env:
      INVENTORY: "true"
      HOSTNAME: 1st_couchbase_host
      PORT: 8091
      QUERY_PORT: 8093
      USERNAME: couchbase_user
      PASSWORD: couchbase_password
    interval: 60s
    labels:
      env: production
      role: load_balancer
    inventory_source: config/couchbase

  - name: nri-couchbase
    env:
      METRICS: "true"
      HOSTNAME: 2nd_couchbase_host
      PORT: 8091
      QUERY_PORT: 8093
      USERNAME: couchbase_user
      PASSWORD: couchbase_password
    interval: 15s
    labels:
      env: production
      role: load_balancer

Find and use data

Integration data is reported to integration dashboards.

Couchbase data is attached to the following event types:

CouchbaseBucketSample
CouchbaseClusterSample
CouchbaseNodeSample
CouchbaseQueryEngineSample

You can query this data for troubleshooting purposes or to create custom charts and dashboards.

For more on how to find and use your data, see Understand integration data.

Metric data

The Couchbase integration collects the following metric data attributes. Some metric names are prefixed with a category indicator and a period, such as cluster. or node..

Couchbase bucket sample metrics

These attributes are attached to the CouchbaseBucketSample event type.

Metric	Description
`bucket.activeResidentItemsRatio`	Percentage of active items cached in RAM in this bucket.
`bucket.averageDiskCommitTimeInMilliseconds`	The average disk commit time of the bucket, in milliseconds.
`bucket.averageDiskUpdateTimeInMilliseconds`	The average disk update time of the bucket, in milliseconds.
`bucket.cacheMissRatio`	Percentage of reads per second to this bucket from disk as opposed to RAM.
`bucket.currentConnections`	Number of connections to this server, including connections from external client SDKs, proxies, TAP requests, and internal statistic gathering.
`bucket.dataUsedInBytes`	Amount of data used by this bucket, in bytes.
`bucket.decrementHitsPerSecond`	The number of decrement hits per second of the bucket.
`bucket.decrementMissesPerSecond`	The number of decrement misses per second of the bucket.
`bucket.deleteHitsPerSecond`	The number of delete hits per second for this bucket.
`bucket.deleteMissesPerSecond`	The number of delete misses per second for this bucket.
`bucket.diskCreateOperationsPerSecond`	Number of new items created on disk per second for this bucket.
`bucket.diskFetchesPerSecond`	The number of operations required per second to fetch items from disk on the bucket.
`bucket.diskUpdateOperationsPerSecond`	Number of items updated on disk per second for this bucket.
`bucket.diskUsedInBytes`	The amount of disk space in use for the bucket, in bytes.
`bucket.diskWriteQueue`	Number of items waiting to be written to disk in the bucket.
`bucket.ejectionsPerSecond`	Total number of items per second being ejected to disk in this bucket
`bucket.evictionPolicy`	The eviction policy of the bucket.
`bucket.evictionsPerSecond`	The number of items per second evicted from the bucket.
`bucket.getHitsPerSecond`	Number of get operations per second for data that this bucket contains.
`bucket.getMissesPerSecond`	Number of get operations per second for data that this bucket does not contain.
`bucket.hitRatio`	Percentage of get requests served with data from this bucket.
`bucket.incrementHitsPerSecond`	The number of increment hits per second of the bucket.
`bucket.incrementMissesPerSecond`	The number of increment misses per second of the bucket.
`bucket.itemCount`	The number of objects stored in the bucket.
`bucket.memoryHighWaterMarkInBytes`	High water mark for auto-evictions on the bucket, in bytes.
`bucket.memoryLowWaterMarkInBytes`	Low water mark for auto-evictions on the bucket, in bytes.
`bucket.memoryUsedInBytes`	The amount of RAM used for the bucket, in bytes.
`bucket.metadataInRAMInBytes`	Amount of RAM used for metadata on this bucket, in bytes.
`bucket.missesPerSecond`	The number of misses per second of the bucket.
`bucket.nodeLocator`	Type of node locator.
`bucket.outOfMemoryErrorsPerSecond`	Number of hard out of memory errors for this bucket.
`bucket.OverheadInBytes`	The extra memory used by transient data (persistence queues, replication queues, checkpoints, etc.) on the bucket, in bytes.
`bucket.pendingResidentItemsRatio`	Percentage of pending items cached in RAM in this bucket.
`bucket.quotaUtilization`	The percent of RAM quota currently in use on the bucket.
`bucket.readOperationsPerSecond`	The number of reads (get operations) per second from this bucket.
`bucket.readRatePerSecond`	The bytes read per second of the bucket.
`bucket.replicaIndex`	Defines if the bucket has replica indexes enabled.
`bucket.replicaNumber`	Number of replicas of this bucket.
`bucket.replicaResidentItemsRatio`	Percentage of replica items cached in RAM in this bucket.
`bucket.residentItemsRatio`	Percentage of all items cached in RAM in this bucket.
`bucket.temporaryOutOfMemoryErrorsPerSecond`	Number of back-offs sent per second to client SDKs due to out of memory situations from this bucket.
`bucket.threadsNumber`	The number of concurrent readers and writers for the data bucket.
`bucket.totalOperationsPerSecond`	The total operations per second of the bucket.
`bucket.writeOperationsPerSecond`	The number of writes (set operations) per second to this bucket.
`bucket.writeRatePerSecond`	The bytes written of the bucket.

Couchbase cluster sample metrics

These attributes are attached to the CouchbaseClusterSample event type.

Metric	Description
`cluster.autoFailoverCount`	The number of auto failovers on the cluster.
`cluster.autoFailoverEnabled`	Indicates if failover is enabled on the cluster.
`cluster.databaseFragmentationThreshold`	The percentage level within the database at which compaction occurs.
`cluster.diskFreeInBytes`	The free disk space on this cluster, in bytes.
`cluster.diskQuotaTotalInBytes`	Total disk space available to Couchbase, in bytes.
`cluster.diskTotalInBytes`	Total disk space available, in bytes.
`cluster.diskUsedbyDataInBytes`	Disk used by bucket data on this cluster, in bytes.
`cluster.diskUsedInBytes`	The used disk space on this cluster, in bytes.
`cluster.indexFragmentationThreshold`	The percentage level within indexes at which compaction occurs.
`cluster.maximumBucketCount`	Maximum number of buckets this cluster supports.
`cluster.memoryQuotaTotalInBytes`	Total RAM available to Couchbase, in bytes.
`cluster.memoryQuotaTotalPerNodeInBytes`	Total RAM available to Couchbase, per node, in bytes.
`cluster.memoryQuotaUsedInBytes`	Total RAM used by Couchbase, in bytes.
`cluster.memoryQuotaUsedPerNodeInBytes`	Total RAM used by Couchbase, per node, in bytes.
`cluster.memoryTotalInBytes`	The total RAM on this cluster, in bytes.
`cluster.memoryUsedByDataInBytes`	Total RAM used by bucket data on this cluster, in bytes.
`cluster.memoryUsedInBytes`	The total RAM used on this cluster, in bytes.
`cluster.viewFragmentationThreshold`	The percentage of fragmentation within all the view index files at which compaction is triggered.

Couchbase node sample metrics

These attributes are attached to the CouchbaseNodeSample event type.

Metric	Description
`node.cpuUtilization`	The CPU utilization of the node.
`node.memoryFreeInBytes`	The free memory of the node, in bytes.
`node.memoryTotalInBytes`	The total memory allocated to the node, in bytes.
`node.recoveryType`	The recovery type of the node.
`node.services`	The services of the node.
`node.status`	The status of the node. (`0` = unhealthy, `1` = healthy)
`node.swapTotalInBytes`	The total swap space of the node, in bytes.
`node.swapUsedInBytes`	The used swap space of the node, in bytes.
`node.uptimeInMilliseconds`	The uptime of the node, in milliseconds.

Couchbase query engine sample metrics

These attributes are attached to the CouchbaseQueryEngineSample event type.

Metric	Description
`queryengine.activeRequests`	Current number of active requests.
`queryengine.averageRequestTimeInMilliseconds`	Average request time of this query engine, in milliseconds.
`queryengine.completedLimit`	Number of queries that Couchbase will keep in the query log.
`queryengine.completedRequests`	Current number of completed requests.
`queryengine.completedThresholdInMilliseconds`	Minimum time query must take to be logged in the Couchbase query log, in milliseconds.
`queryengine.cores`	Number of cores available for this query engine.
`queryengine.garbageCollectionNumber`	Number of the last garbage collection.
`queryengine.garbageCollectionPaused`	Percent of time that garbage collection is paused.
`queryengine.garbageCollectionTimePausedInMilliseconds`	Number of milliseconds that garbage collection is paused, in milliseconds.
`queryengine.medianRequestTimeInMilliseconds`	Median request time of this query engine, in milliseconds.
`queryengine.preparedStatementUtilization`	Percentage of requests that are prepared statements.
`queryengine.requestsLast15MinutesPerSecond`	Requests per second average over the past 15 minutes.
`queryengine.requestsLast1MinutesPerSecond`	Requests per second average over the past minute.
`queryengine.requestsLast5MinutesPerSecond`	Requests per second average over the past 5 minutes.
`queryengine.requestTime80thPercentileInMilliseconds`	80th percentile of request time of this query engine, in milliseconds.
`queryengine.requestTime95thPercentileInMilliseconds`	95th percentile of request time of this query engine, in milliseconds.
`queryengine.requestTime99thPercentileInMilliseconds`	99th percentile of request time of this query engine, in milliseconds.
`queryengine.systemCPUUtilization`	CPU utilization of this query engine
`queryengine.systemMemoryInBytes`	The virtual address space reserved by this query engine, in bytes.
`queryengine.totalMemoryInBytes`	Cumulative amount of memory allocated for heap objects by this query engine, in bytes.
`queryengine.totalThreads`	Total threads used by this query engine.
`queryengine.uptimeInMilliseconds`	Uptime of this query engine, in milliseconds
`queryengine.usedMemoryInBytes`	Amount of memory allocated for heap objects for this query engine, in bytes.
`queryengine.userCPUUtilization`	User CPU utilization of this query engine.

Inventory data

The Couchbase integration captures the configuration parameters of the Couchbase database. The data is available on the Inventory page in the infrastructure UI, under the config/couchbase source. For more about inventory data, see Understand data.

The integration captures data for the following Couchbase configuration parameters:

Name	Description
`Node locator`	Type of node locator.
`Proxy port`	Proxy port on which the bucket communicates.
`Type`	The type of bucket.
`UUID`	The UUID of the bucket.

Name	Description
`Collection node`	The node used to collect metrics.
`Couchbase version`	The version of Couchbase running on this cluster.
`UUID`	The UUID of the cluster.

Name	Description
`Cluster membership`	The cluster membership of the node.
`Hostname`	The hostname of the node.
`Operating system`	The operating system of the node.
`Port`	The port of the node.
`Recovery type`	The recovery type of the node.
`Services`	A comma-separated list of services of the node.
`Version`	The version of Couchbase running on this node.

Name	Description
`Node hostname`	The hostname of the node this query engine runs on.
`Node port`	The port of the node this query engine runs on.
`Version`	The version of this query engine.

Check the source code

This integration is open source software. That means you can browse its source code and send improvements, or create your own fork and build it.

Compatibility and requirements

Quick start

Install

ECS

Kubernetes

Linux

Windows

Update your integration

Post-installation tasks

Configure the integration

Couchbase configuration options

Labels

Example configurations

Basic configuration

Basic configuration with different metric/inventory intervals

Environment variables replacement

Multi-instance monitoring

Find and use data

Metric data

Couchbase bucket sample metrics

Couchbase cluster sample metrics

Couchbase node sample metrics

Couchbase query engine sample metrics

Inventory data

Bucket parameters

Cluster parameters

Node parameters

Query engine parameters

Check the source code