• English日本語한국어
  • Log inStart now

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

Install

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

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

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:

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.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.