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.
Before installing the integration, make sure that you meet the following requirements:
- If Couchbase is not running on Kubernetes, you must install the infrastructure agent on a host that's running Couchbase. Otherwise:
- If running on Kubernetes, see these requirements.
- If running on ECS, see these requirements.
Quick start
Instrument your Couchbase cluster quickly and send your telemetry data with guided install. Our guided install creates a customized CLI command for your environment that downloads and installs the New Relic CLI and the infrastructure agent.
Ready to get started? Click one of these button to try it out.
Our guided install uses the infrastructure agent to set up the Couchbase integration. Not only that, it 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, you can find other methods below to get started monitoring your Couchbase cluster.
Install and activate
To install the Couchbase integration, follow the instructions for your environment:
Additional notes:
- Advanced: Integrations are also available in tarball format to allow for install outside of a package manager.
- On-host integrations do not automatically update. For best results, regularly update the integration package and the infrastructure agent.
Did this doc help with your installation?
Configuration
Configure the integration
There are several ways to configure the integration, depending on how it was installed:
- If enabled via Kubernetes: see Monitor services running on Kubernetes.
- If enabled via Amazon ECS: see Monitor services running on ECS.
- If installed on-host: edit the config in the integration's YAML config file,
couchbase-config.yml
.
An integration's YAML-format configuration is where you can place required login credentials and configure how data is collected. Which options you change depend on your setup and preference.
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.
Important
If you are still using our legacy configuration/definition files, please refer to this document for help.
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 Instance Settings
The Couchbase integration collects both metrics(M) and inventory(I) information. In the table, use the Applies To column for the settings available to each collection:
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 | 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 | false | |
INVENTORY | Set to | false |
The values for these settings can be defined in several ways:
- Adding the value directly in the config file. This is the most common way.
- Replacing the values from environment variables using the
{{}}
notation. This requires infrastructure agent v1.14.0+. Read more here or see the example below. - Using secrets management. Use this to protect sensitive information, such as passwords that would be exposed in plain text on the configuration file. For more information, see Secrets management.
Labels/Custom attributes
You can further decorate your metrics using labels. Labels allow you to add key/value pair attributes to your metrics, which you can then use to query, filter, or group your metrics on.
Our default sample config file includes examples of labels; however, as they are 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 |
---|---|
| Percentage of active items cached in RAM in this bucket. |
| The average disk commit time of the bucket, in milliseconds. |
| The average disk update time of the bucket, in milliseconds. |
| Percentage of reads per second to this bucket from disk as opposed to RAM. |
| Number of connections to this server, including connections from external client SDKs, proxies, TAP requests, and internal statistic gathering. |
| Amount of data used by this bucket, in bytes. |
| The number of decrement hits per second of the bucket. |
| The number of decrement misses per second of the bucket. |
| The number of delete hits per second for this bucket. |
| The number of delete misses per second for this bucket. |
| Number of new items created on disk per second for this bucket. |
| The number of operations required per second to fetch items from disk on the bucket. |
| Number of items updated on disk per second for this bucket. |
| The amount of disk space in use for the bucket, in bytes. |
| Number of items waiting to be written to disk in the bucket. |
| Total number of items per second being ejected to disk in this bucket |
| The eviction policy of the bucket. |
| The number of items per second evicted from the bucket. |
| Number of get operations per second for data that this bucket contains. |
| Number of get operations per second for data that this bucket does not contain. |
| Percentage of get requests served with data from this bucket. |
| The number of increment hits per second of the bucket. |
| The number of increment misses per second of the bucket. |
| The number of objects stored in the bucket. |
| High water mark for auto-evictions on the bucket, in bytes. |
| Low water mark for auto-evictions on the bucket, in bytes. |
| The amount of RAM used for the bucket, in bytes. |
| Amount of RAM used for metadata on this bucket, in bytes. |
| The number of misses per second of the bucket. |
| Type of node locator. |
| Number of hard out of memory errors for this bucket. |
| The extra memory used by transient data (persistence queues, replication queues, checkpoints, etc.) on the bucket, in bytes. |
| Percentage of pending items cached in RAM in this bucket. |
| The percent of RAM quota currently in use on the bucket. |
| The number of reads (get operations) per second from this bucket. |
| The bytes read per second of the bucket. |
| Defines if the bucket has replica indexes enabled. |
| Number of replicas of this bucket. |
| Percentage of replica items cached in RAM in this bucket. |
| Percentage of all items cached in RAM in this bucket. |
| Number of back-offs sent per second to client SDKs due to out of memory situations from this bucket. |
| The number of concurrent readers and writers for the data bucket. |
| The total operations per second of the bucket. |
| The number of writes (set operations) per second to this bucket. |
| The bytes written of the bucket. |
Couchbase cluster sample metrics
These attributes are attached to the CouchbaseClusterSample
event type.
Metric | Description |
---|---|
| The number of auto failovers on the cluster. |
| Indicates if failover is enabled on the cluster. |
| The percentage level within the database at which compaction occurs. |
| The free disk space on this cluster, in bytes. |
| Total disk space available to Couchbase, in bytes. |
| Total disk space available, in bytes. |
| Disk used by bucket data on this cluster, in bytes. |
| The used disk space on this cluster, in bytes. |
| The percentage level within indexes at which compaction occurs. |
| Maximum number of buckets this cluster supports. |
| Total RAM available to Couchbase, in bytes. |
| Total RAM available to Couchbase, per node, in bytes. |
| Total RAM used by Couchbase, in bytes. |
| Total RAM used by Couchbase, per node, in bytes. |
| The total RAM on this cluster, in bytes. |
| Total RAM used by bucket data on this cluster, in bytes. |
| The total RAM used on this cluster, in bytes. |
| 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 |
---|---|
| The CPU utilization of the node. |
| The free memory of the node, in bytes. |
| The total memory allocated to the node, in bytes. |
| The recovery type of the node. |
| The services of the node. |
| The status of the node. ( |
| The total swap space of the node, in bytes. |
| The used swap space of the node, in bytes. |
| The uptime of the node, in milliseconds. |
Couchbase query engine sample metrics
These attributes are attached to the CouchbaseQueryEngineSample
event type.
Metric | Description |
---|---|
| Current number of active requests. |
| Average request time of this query engine, in milliseconds. |
| Number of queries that Couchbase will keep in the query log. |
| Current number of completed requests. |
| Minimum time query must take to be logged in the Couchbase query log, in milliseconds. |
| Number of cores available for this query engine. |
| Number of the last garbage collection. |
| Percent of time that garbage collection is paused. |
| Number of milliseconds that garbage collection is paused, in milliseconds. |
| Median request time of this query engine, in milliseconds. |
| Percentage of requests that are prepared statements. |
| Requests per second average over the past 15 minutes. |
| Requests per second average over the past minute. |
| Requests per second average over the past 5 minutes. |
| 80th percentile of request time of this query engine, in milliseconds. |
| 95th percentile of request time of this query engine, in milliseconds. |
| 99th percentile of request time of this query engine, in milliseconds. |
| CPU utilization of this query engine |
| The virtual address space reserved by this query engine, in bytes. |
| Cumulative amount of memory allocated for heap objects by this query engine, in bytes. |
| Total threads used by this query engine. |
| Uptime of this query engine, in milliseconds |
| Amount of memory allocated for heap objects for this query engine, in bytes. |
| 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 Infrastructure Inventory page, 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.