Couchbase
- Product information
- Release notes
Overview
The Couchbase extension is designed to monitor Couchbase databases. It provides monitoring metrics at the cluster and node level.
This initial release focuses on support for Capella, Couchbase's cloud database platform. Future versions will add support for Couchbase Server self-hosted solution.
Monitoring Cappella is handled by deploying the extension on an ActiveGate.
Get started
Set up monitoring
Virtual machine
If your Couchbase is running on a virtual machine directly, you will need to install OneAgent on that virtual machine to get started.
Kubernetes workload
If your Couchbase is running as a workload in Kubernetes, please refer to the Kubernetes deployment start guide.
Openshift workload
If your Couchbase is running as a workload in OpenShift, please refer to the OpenShift deployment start guide.
OpenTelemetry
If you are instrumenting Couchbase with OpenTelemetry then:
- Ensure that the OneAgent feature "OpenTelemetry Java Instrumentation agent support" is activated to get full tracing and metric insight (OneAgent version 1.237 or newer needed).
- Instrument the java client with OpenTelemetry.
- Ensure to store the span attributes.
Extension
Activate the Couchbase extension to get further metrics.
The Couchbase extension is designed to monitor Couchbase databases. It provides monitoring metrics at the cluster and node level.
The extension supports Capella, Couchbase's cloud database platform and Couchbase Server version 7+.
Details
Configuration
To configure the Couchbase Capella extension, add this extension and create a new Monitoring Configuration.
Successful configuration of the extension requires several corresponding settings in the Capella/Couchbase Server Admin UI. Below are guidelines for the required configurations.
Connection Hostname
Capella: This is the Capella Connection String. In the Capella UI, go to the Connect tab on a Database and copy the full connection string. Server: IP of a Couchbase Node. The Couchbase Node must be accessible from the ActiveGate the extension is running on.
User Credentials
Capella: The extension requires a set of Capella credentials (username / password) that has Read Access to All Buckets and All Scopes in your Database (as noted, the required external_stats_reader role is only granted when a Database Credential is given Read Access to all Buckets in a Database). Credentials can be created in the Capella UI by going to Settings -> Database Access -> Create Database Access (see Couchbase's Configure Database Credentials)
Server: Create a user with Read-Only Admin permissions.
Security Certificate
The Security Certificate for your Database. In the Capella UI, select the Database, go to Settings -> Security Certificate, and click on Copy. This will give you a PEM-formatted text.
Allowed IP Addresses
Before any client can connect to a Capella Database, the client's IP address must be added to the Database's Allowed IP list.
Note: For Allowed IP address, you must find the external IP address of the ActiveGate(s) you are running the extension on and add those IPs to the allowed IP address setting.
Compatibility information
- Linux OS or Windows
- Couchbase version 4.3+
The extension requires:
- ActiveGate version 1.270+
- Dynatrace version 1.270+
- Couchbase version 7+
Extension content
Feature sets
Below is a complete list of the feature sets provided in this version. To ensure a good fit for your needs, individual feature sets can be activated and deactivated by your administrator during configuration.
| Metric name | Metric key | Description | Unit |
|---|---|---|---|
| XDCR replicated docs | couchbase.xdcr_docs_processed_total | Number of documents processed for a Replication | Count |
| XDCR docs received | couchbase.xdcr_docs_received_from_dcp_total | Number of Document Mutations received from the Data Service | Count |
| XDCR docs written | couchbase.xdcr_docs_written_total | Number of docs Document Mutations written/sent to the Target | Count |
| XDCR write operations | couchbase.xdcr_set_docs_written_total | Number of Set operations successfully written to the Target | Count |
| Metric name | Metric key | Description | Unit |
|---|---|---|---|
| Current MCBP/DCP Connections | couchbase.kv_curr_connections | Current number of MCBP/DCP connections | Count |
| Waiting for commit (bucket) | couchbase.kv_disk_seconds_bucket | Waiting for a commit after a batch of updates | Second |
| Waiting for commit (count) | couchbase.kv_disk_seconds_count.gauge | Waiting for a commit after a batch of updates | Second |
| Waiting for commit (sum) | couchbase.kv_disk_seconds_sum | Waiting for a commit after a batch of updates | Second |
| Disk used by Bucket | couchbase.kv_ep_db_data_size_bytes | Total size of valid data in db files | Byte |
| Disk drain rate | couchbase.kv_ep_diskqueue_drain | Total drained items on disk queue | Count |
| Enqueued items on disk queue | couchbase.kv_ep_diskqueue_fill | Total enqueued items on disk queue | Count |
| Total memory used in disk queue | couchbase.kv_ep_diskqueue_memory_bytes | Total memory used in disk queue | Byte |
| Disk used percent by node | couchbase.kv_ep_magma_total_disk_usage_bytes | Disk used percent by node | Byte |
| Items queued for storage | couchbase.kv_ep_queue_size | Number of items queued for storage | Count |
| Temporary out of memory errors by bucket | couchbase.kv_ep_tmp_oom_errors | Number of times temporary OOMs happened while processing operations | Count |
| Total engine memory usage | couchbase.kv_mem_used_bytes | Engine's total memory usage | Byte |
| Get ops per second | couchbase.kv_vb_ops_get | Get Ops Per Second | PerSecond |
| Set ops per second | couchbase.kv_vb_ops_set | Set Ops Pet Second | PerSecond |
| Active item resident ratio | couchbase.kv_vb_perc_mem_resident_ratio | Active item resident ratio | Percent |
| VB queue drain | couchbase.kv_vb_queue_drain | VB queue drain | Unspecified |
| VB queue fill | couchbase.kv_vb_queue_fill | VB queue fill | Unspecified |
| VB queue pending | couchbase.kv_vb_queue_pending_bytes | VB queue pending | Unspecified |
| VB queue size | couchbase.kv_vb_queue_size | VB queue size | Unspecified |
| Metric name | Metric key | Description | Unit |
|---|---|---|---|
| Documents indexed per second | couchbase.index_avg_drain_rate | Average number of documents indexed per second, for this index | PerSecond |
| Average size of index items | couchbase.index_avg_item_size | Average size of the indexed items | Byte |
| Uncompressed index data size | couchbase.index_data_size | The approximate size of the valid uncompressed index data | Byte |
| Index total disk space | couchbase.index_disk_size | Total disk space taken up by this index after compression. This includes index data files, checkpoints etc. | Byte |
| Records in memory ratio | couchbase.index_resident_percent | Ratio of records in memory to total records, for this index | Percent |
| Metric name | Metric key | Description | Unit |
|---|---|---|---|
| CPU Utilization (Deprecated in CB v7.6.0) | couchbase.sysproc_cpu_utilization | CPU utilization rate | Unspecified |
| Resident memory used | couchbase.sysproc_mem_resident | Amount of resident memory used | Byte |
| Memory used | couchbase.sysproc_mem_size | Amount of memory used | Byte |
| CPU Utilization | couchbase.sys_cpu_utilization_rate | CPU utilization rate in the control group | Percent |
| Metric name | Metric key | Description | Unit |
|---|---|---|---|
| Total active requests | couchbase.n1ql_active_requests | Total number of active requests. | Count |
| Total N1QL requests with at_plus index consistency | couchbase.n1ql_at_plus.count | Total number of N1QL requests with at_plus index consistency. | Count |
| Total audit records sent | couchbase.n1ql_audit_actions.count | The total number of audit records sent to the server. Some requests cause more than one audit record to be emitted. Records in the output queue that have not yet been sent to the server are not counted. | Count |
| Total failed audit records sent | couchbase.n1ql_audit_actions_failed.count | The total number of audit records sent to the server that failed. | Count |
| Potentially auditable requests with no audit action | couchbase.n1ql_audit_requests_filtered.count | The number of potentially auditable requests that cause no audit action to be taken. | Count |
| Potentially auditable requests sent to query engine | couchbase.n1ql_audit_requests_total.count | The total number of potentially auditable requests sent to the query engine. | Count |
| Cancelled requests | couchbase.n1ql_cancelled.count | Total number of cancelled requests. | Count |
| Delete operations | couchbase.n1ql_deletes.count | Total number of DELETE operations. | Count |
| N1QL error count | couchbase.n1ql_errors.count | The total number of N1QL errors returned so far. | Count |
| Secondary index scans | couchbase.n1ql_index_scans.count | Total number of secondary index scans. | Count |
| Insert operations | couchbase.n1ql_inserts.count | Total number of INSERT operations. | Count |
| Invalid requests | couchbase.n1ql_invalid_requests.count | Total number of requests for unsupported endpoints. | Count |
| Document mutations | couchbase.n1ql_mutations.count | Total number of document mutations. | Count |
| Prepared statements executed | couchbase.n1ql_prepared.count | Total number of prepared statements executed. | Count |
| Primary index scans | couchbase.n1ql_primary_scans.count | Total number of primary index scans. | Count |
| Query process time | couchbase.n1ql_request_time.count | Total end-to-end time to process all queries. | NanoSecond |
| N1QL requests | couchbase.n1ql_requests.count | Total number of N1QL requests. | Count |
| Queries longer than 1000ms | couchbase.n1ql_requests_1000ms.count | Number of queries that take longer than 1000ms. | Count |
| Queries longer than 250ms | couchbase.n1ql_requests_250ms.count | Number of queries that take longer than 250ms. | Count |
| Queries longer than 5000ms | couchbase.n1ql_requests_5000ms.count | Number of queries that take longer than 5000ms. | Count |
| Queries longer than 500ms | couchbase.n1ql_requests_500ms.count | Number of queries that take longer than 500ms. | Count |
| Results (document) returned count | couchbase.n1ql_result_count | Total number of results (documents) returned by the query engine. | Count |
| Result size | couchbase.n1ql_result_size.count | Total size of data returned by the query engine. | Count |
| N1QL requests with request_plus consistency | couchbase.n1ql_scan_plus.count | Total number of N1QL requests with request_plus index consistency. | Count |
| Select requests | couchbase.n1ql_selects.count | Total number of SELECT requests. | Count |
| Time to execute queries | couchbase.n1ql_service_time.count | Time to execute all queries. | NanoSecond |
| Elapsed transaction time | couchbase.n1ql_transaction_time.count | Total elapsed time of transactions so far. | NanoSecond |
| Transaction count | couchbase.n1ql_transactions.count | Total number of transactions. | Count |
| N1QL requests with not_bounded consistency | couchbase.n1ql_unbounded.count | Total number of N1QL requests with not_bounded index consistency. | Count |
| Update requests | couchbase.n1ql_updates.count | Total number of UPDATE requests. | Count |
| N1QL warnings | couchbase.n1ql_warnings.count | The total number of N1QL warnings returned so far. | Count |
Full version history
Full version history
This version contains a breaking change that will require recreation of monitoring configurations. This version has no new features for users who are currently monitoring Capella databases and no need for Capella users to upgrade at this time. Future versions will add new features and will require an upgrade and recreation of monitoring configurations.
- Adds support for self-hosted clusters monitored remotely from ActiveGate
- Improved first run experience. Adds Fastcheck that checks credentials and provides feedback in Extension app monitoring configuration logs
- Improved handling of connection strings that lack ports. The extension will now determine if the cluster is self-hosted and assign a default port based on cluster type.
- Adds the version of the Couchbase cluster to the metric metadata
- Adds
couchbase.sys_cpu_utilization_rateto match CPU metric provided by Couchbase admin UI
Full version history
v1.1.0
- Node discovery is now done via the API
- Enhanced node properties
- Improved handling for malformed dimensions
- Refactoring of code
Full version history
- Increased allowed certificate length to 2600 characters
- Clarified wording around settings related to the Connection String