You are viewing the documentation for a prerelease version.

View Latest

Manage Statistics

Statistics on Couchbase Server can be monitored; per bucket, per node, and per cluster.

Understanding Statistics Management

Couchbase Server provides statistics; which are updated continuously, and so always represent the current state of the cluster. Statistics refer to buckets, nodes, and clusters. The Full Admin, Cluster Admin, and Read-Only Admin roles support the reading of cluster and all bucket statistics. The Bucket Admin role supports the reading of statistics on specified buckets. See Roles, for more information.

Statistics can be viewed by means of Couchbase Web Console, the Couchbase CLI, and the REST API.

Manage Statistics with the UI

Statistics can be assembled and monitored on the Dashboard of Couchbase Web Console. This is visible by default after login; and can at any time be displayed by left-clicking on the Dashboard tab, in the left-hand navigation bar:


Initially, prior to any definitions having been made, the Dashboard appears as follows:


At the foot of the screen, numbers are displayed; to indicate which cluster-nodes are active, failed-over, pending rebalance, and inactive. Near the top, a notification is provided, regarding buckets:


Couchbase Web Console organizes statistics by bucket. Therefore, until a bucket is added to the cluster, no statistics can be shown. To add a bucket, left-click on one of the options provided by the notification. Either left-click on Buckets, to add a custom bucket; or, left-click on sample bucket, to install a sample bucket.

The following examples assume that the travel-sample bucket has been installed. This is indicated by the control at the right-hand side of the screen:


Once multiple buckets have been created, this control can be used to make an appropriate selection, and so view the corresponding statistics.

Add a Group

In the context of statistics-display, a group consists of a number of different animated charts, which are associated with one another for purposes of display. Once a group is defined, individual charts can be added incrementally. The charts assigned to a group can be displayed and hidden as a single unit; which optimizes use of screen space, when multiple groups have been defined.

To define a group, access the Add Group control, in the upper part of the screen:


Left-clicking displays a pull-down dialog:


Establish focus in the new scenario…​ editable text-field. This causes the pull-down dialog to expand further:


In the new scenario…​ field, type a name for the group being defined. In the add optional description…​ field, add a brief description of the group’s purpose. Then, left-click on the Save button:


The Add Group panel now appears as follows:


This indicates that a new group, named Data Activity, has been defined. It can now be used to display statistics on the travel-sample bucket.

Add a Chart

To add a chart to a defined group, left-click on the cross at the center of the blank chart-area that is displayed:


The Add a Chart dialog now appears:


This dialog allows selection of information that will be displayed in a chart, associated with the established group. The primary categories, which are horizontally distributed across the upper area of the dialog, are System, Index, Query, Data, and XDCR. By default, System is displayed, with a seres of checkboxes as its accompanying fields. Selecting any of the other options correspondingly changes the accompanying fields.

Note that the dialog also contains, towards the bottom, additional options. Display Data From determines whether the chart displays data from the current node, or from the entire cluster. Chart Size provides a pull-down menu, whereby the size of the displayed chart is selected. Group allows selection among currently defined groups.

Left-click on Data. The display now changes as follows:


A button is now displayed for each of the Data subcategories; which are Ops, Memory, Disk, VBucket, Disk Queues, and DCP Queues. Left-click on the Ops subcategory:


Once again, the Add a Chart dialog is redisplayed: this time, options for representing operations are provided, as checkboxes:


Access the ops per second checkbox. Note that when the mouse cursor is hovered over the checkbox, a tooltip appears:


Check the checkbox. Then, save the configuration by left-clicking on the Save Chart button, at the lower right of the dialog:


The Data Activity group now appears as follows:


The ops per second chart is now displayed, with the control for creating a new chart situated at its right.

Edit a Chart

Couchbase Web Console allows charts to be interactively edited.

Left-click on the icon at the upper-right of the existing chart:


Controls for editing and deleting the chart are now displayed:


To edit the current chart, click on the left icon:


This brings up the Edit a Chart dialog, which is similar in appearance to the Add a Chart dialog, which was used to create the current chart. To add information to the current chart, make an appropriate selection. For example, under the System subcategory, select Maximum CPU utilization %:


After this setting has been saved, the chart displayes data for both of the selected statistics. Observability can be enhanced by hovering the mouse cursor over the chart: a pop-up appears, detailing information.


The pop-up displays statistics that correspond to the marked coordinates over which the mouse is hovered; and also displays the time of day to which the coordinates correspond.

Observability can also be enhanced by enlarging the size of the chart. Within the Edit a Chart dialog, access and modify the Chart Size control:


Then save. The chart is correspondingly redisplayed:


Note that the time-granularity for all information-display can be changed, by accessing the control at the upper-center region of the Dashboard. The default is hour:


Pick an alternative from the displayed pop-up menu:


A minute-based granularity for information-display is now provided:


To delete a chart, use the trashcan control, at the upper-right of the chart:


A request for confirmation is displayed:


Left-click on Confirm, to remove the chart.

Note that each group also has a trashcan icon, which can be used to delete the entire group.

Working with Multiple Charts and Groups

The Dashboard can be configured with multiple groups, each containing multiple charts. Groups can be displayed and hidden as appropriate, in order to optimize use of screen space.

The following example shows two groups, each with multiple charts displayed:


Manage Statistics with the CLI

On the command-line, statistics can be managed with the cli/cbstats-intro.adoc tool. This allows a bucket to be specified as the source of statistics. Port 11210 must be specified.

For example, the memory option returns statistics on memory for the specified bucket:

/opt/couchbase/bin/cbstats -b travel-sample -u Administrator -p password \
localhost:11210 memory

If successful, the command returns the following:

 bytes:                     38010040
 ep_blob_num:               31591
 ep_blob_overhead:          2159511
 ep_item_num:               3584
 ep_kv_size:                24495752
 ep_max_size:               104857600
 ep_mem_high_wat:           89128960
 ep_mem_high_wat_percent:   0.85
 ep_mem_low_wat:            78643200
 ep_mem_low_wat_percent:    0.75
 ep_oom_errors:             0
 ep_overhead:               5194392
 ep_storedval_num:          31591
 ep_storedval_overhead:     2159511
 ep_storedval_size:         2527280
 ep_tmp_oom_errors:         0
 ep_value_size:             22306240
 mem_used:                  38010040
 mem_used_estimate:         38010040
 mem_used_merge_threshold:  524288
 total_allocated_bytes:     67864856
 total_fragmentation_bytes: 4220648
 total_heap_bytes:          111050752
 total_metadata_bytes:      6175864
 total_resident_bytes:      103907328
 total_retained_bytes:      18448384

The vbucket option returns statistics for all vBuckets for the specified bucket. The output can be filtered, so that a particular vBucket can be examined:

/opt/couchbase/bin/cbstats -b travel-sample -u Administrator -p password \
localhost:11210 vbucket | grep 1014

This produces the following output:

 vb_1014: active

For more information on available options, see cli/cbstats-intro.adoc.

Manage Statistics with the REST API

The Couchbase-Server REST API allows statistics to be gathered either from the cluster or from the individual bucket.

Get Cluster Statistics

Cluster statistics can be accessed by means of the /pools/default URI, as follows:

curl -v -X GET -u Administrator:password localhost:8091/pools/default | jq

Note that in this example, output is piped to the jq tool: this formats the output, and so improves readability. A sample of the (extensive) formatted output might appear as follows:

  "name": "default",
  "nodes": [
      "systemStats": {
        "cpu_utilization_rate": 12.08791208791209,
        "swap_total": 536866816,
        "swap_used": 218357760,
        "mem_total": 1040723968,
        "mem_free": 194670592,
        "mem_limit": 1040723968,
        "cpu_cores_available": 1
      "interestingStats": {
        "cmd_get": 0,
        "couch_docs_actual_disk_size": 95912798,
        "couch_docs_data_size": 46982656,
        "couch_spatial_data_size": 0,
        "couch_spatial_disk_size": 0,
        "couch_views_actual_disk_size": 0,

The full output includes information on:

  • Memory and disks: how much space is available in total, how much is currently free, etc.

  • Nodes, CPUs, uptime, ports being used, services deployed.

  • URIs for important Couchbase Server endpoints, such as rebalance, failOver, ejectNode, and setAutoCompaction.

  • Cluster settings, such as viewFragmentationThreshold and indexCompactionMode; and counters for operations such as rebalance and failover.

For more information, see Retrieving Cluster Information.

Get Bucket Statistics

To get statistics for an individual bucket, use the /buckets/<bucket-name>/stats URI. For example:

curl -v GET -u Administrator:password \
http://localhost:8091/pools/default/buckets/travel-sample/stats | jq

Extracts from the (extensive) formatted output might appear as follows:

  "op": {
    "samples": {
      "couch_total_disk_size": [
      "couch_docs_fragmentation": [
      "couch_views_fragmentation": [
      "hit_ratio": [
      "samplesCount": 60,
      "isPersistent": true,
      "lastTStamp": 1553695746640,
      "interval": 1000
    "hot_keys": []

A number of key statistics are thus returned, each applied to each of the specified bucket’s vBuckets.

For more information, see Getting Bucket Statistics.