Setting Alerts

Alerts can be configured; to be dispatched or displayed automatically by Couchbase Server, in order to notify users of specific issues and problems.

HTTP Methods and URIs

GET /settings/alerts

POST /settings/alerts

GET /settings/alerts/limits

POST /settings/alerts/limits

POST /settings/alerts/sendTestEmail

Description

Alerts can be dispatched or displayed automatically by Couchbase Server, in order to highlight specific issues and problems. When an issue arises, an alert is generated, and one or both of the following can be configured to occur:

The alert is sent as an email by Couchbase Server to a configured SMTP server. From there, the email is forwarded to a configured list of email recipients. All cluster-nodes must have network access to the configured SMTP server, for the system to be fully effective.
The alert appears as a pop-up, within Couchbase Web Console.

To configure alerts, either the Full Admin or Cluster Admin role is required.

The GET /settings/alerts method and URI return the current alert settings. The POST /settings/alerts method and URI establish the alert settings.

The GET /settings/alerts/limits method and URI return the current memory-alert thresholds. The POST /settings/alerts/limits method and URI establish the thresholds at which memory-alerts are set, and can also be used to enable or disable individual thresholds.

The POST /settings/alerts/sendTestEmail method and URI configure dispatch of a test email.

Curl Syntax

curl -X GET -u http://<ip-address-or-domain-name>:8091/settings/alerts
  -u <username>:<password>

curl -X POST -u http://<ip-address-or-domain-name>:8091/settings/alerts
  -u <username>:<password>
  -d emailPass=<email-password>
  -d sender=<sender-email-address>
  -d recipients=<list-of-recipient-email-addresses>
  -d emailHost=<ip-address-or-domain-name>
  -d emailPort=<email-server-port-number>
  -d emailEncrypt=[ true | false ]
  -d alerts=<[alert-name]*>
  -d pop_up_alerts=<[alert-name]*>
  -d enabled=[ true | false ]

curl -X GET -u http://<ip-address-or-domain-name>:8091/settings/alerts/limits
  -u <username>:<password>

curl -X POST http://<ip-address-or-domain-name:8091>/settings/alerts/limits
  -u <username>:<password>
  -d historyWarningThreshold=<integer>
  -d lowIndexerResidentPerc=<integer>
  -d maxDiskUsedPerc=<integer>
  -d maxIndexerRamPerc=<integer>
  -d maxOverheadPerc=<integer>
  -d memoryNoticeThreshold=<integer>
  -d memoryWarningThreshold=<integer>
  -d memoryCriticalThreshold=<integer>

curl -X POST http://<ip-address-or-domain-name>:8091/settings/alert/sendTestEmail
  -u <username>:<password>

username and password. The username and password of the administrator who is managing the settings. The Full Admin or Cluster Admin role is required. (See Roles.)
emailPass. The password of the email server that will dispatch the emails. This parameter is optional. The default is an empty string.
sender. The email address of the sender. This parameter is optional. The default value is couchbase@localhost.
recipients. A list of comma-separated email addresses of the intended recipients. This parameter is optional. The default value is root@localhost.
emailHost. The IP address or domain name of the email server to dispatch the alerts. This parameter is optional. The default value is localhost.
emailPort. The port that will be used by the email server. This parameter is optional. The default value is 25.
emailEncrypt. Determines whether emails should be dispatched in encrypted form: the value must be true or false (the default). This parameter is optional.
alerts. A list of email-alert names. If the alert-name is included in the list, a corresponding email-alert will be sent as appropriate, when enabled is true. If the name of an alert is not included in the list, the email-alert is not dispatched. This parameter is optional. The default value contains all alerts: these are listed in Available Alerts.
pop_up_alerts. A list of pop-up-alert names. If the alert-name is included in the list, a corresponding pop-up alert will be displayed as appropriate, when enabled is true. If the name of an alert is not included in the list, the corresponding pop-up alert is not displayed. This parameter is optional. The default value contains all alerts: these are listed in Available Alerts.
enabled. Enables or disables alerts: the value can be true or false (the default). This parameter is optional. If alerts are enabled, any alert that appears in the list that is passed as the value of alerts or pop_up_alerts (see immediately below) will have an email and/or pop-up display generated as appropriate.
historyWarningThreshold. Warns that the change history for one of the buckets is becoming full, across one or more vBuckets. (The size of the change history is administrator-specified for the whole bucket.) The value of historyWarningThreshold must be an integer that represents a percentage: the default value is 90. When the percentage is exceeded for one or more vBuckets, an alert is generated. See Creating and Editing Buckets, for information on establishing the size of the change history.
lowIndexerResidentPerc. Warns that the Index Service is, on a given node, occupying a percentage of available memory that is below an established threshold, which is the value of lowIndexerResidentPerc. The default value is 10.
maxDiskUsedPerc, maxIndexerRamPerc, and maxOverheadPerc. The maximum percentages for disk usage, memory consumption by the Index Service, and overhead. Values must be between 0 and 100.
memoryNoticeThreshold, memoryWarningThreshold, and memoryCriticalThreshold. Thresholds for memory-usage. These are all disabled until the memory_threshold alert is enabled — for email or for pop-up display, or for both — by means of POST /settings/alerts (see Available Alerts for the full list of alerts). Note that even when memory_threshold is enabled, any of these thresholds can be individually disabled, by setting its value to -1. When a threshold is fully enabled, its value is an integer between 1 and 100: the integer specifies the percentage of total system memory that must have been consumed for an email and/or pop-up alert to be correspondingly generated. Thresholds are enabled, disabled, and configured by means of POST /settings/alerts/limits; and their values are retrieved by means of GET /settings/alerts/limits.

The thresholds are intended to be assigned values in ascending order; with memoryNoticeThreshold the lowest, and memoryCriticalThreshold the highest. The default values are, for memoryNoticeThreshold -1 (meaning disabled), for memoryWarningThreshold 90, and for memoryCriticalThreshold 95.

Responses

A successful call returns 200 OK.

Failure to authenticate returns 401 Unauthorized. Incorrect specification of method or URI returns 404 Object Not Found. Failures to specify parameters correctly return 400 Bad Request, with error-messages such as the following:

Failure to specify enabled: {"errors":{"enabled":"The value must be one of the following: [true,false]"}}
Invalid key: {"errors":{"enabled":"The value must be one of the following: [true,false]"}}
Unsupported key: {"errors":{"port":"Unsupported key"}}
Incorrect specification of recipients list: {"errors":{"recipients":"recipients must be a comma separated list of valid email addresses."}}
Incorrect specification of emailEncrypt: {"errors":{"emailEncrypt":"The value must be one of the following: [true,false]"}}
Incorrect specification of sender: {"errors":{"sender":"The value must be a valid email address"}}
Incorrect specification of a memory threshold: {"errors":{"memoryWarningThreshold":"The value must be in range from -1 to 100"}}

Examples

The following returns the default settings for all alerts. Note that the call is piped to the jq command, to facilitate readability.

curl -v -X GET http://localhost:8091/settings/alerts -u Administrator:password | jq '.'

If successful, the command returns 200 OK and the following object, which contains all alerts at their default settings:

{
  "recipients": [
    "root@localhost"
  ],
  "sender": "couchbase@localhost",
  "enabled": false,
  "emailServer": {
    "user": "",
    "pass": "",
    "host": "localhost",
    "port": 25,
    "encrypt": false
  },
  "alerts": [
    "memory_threshold",
    "auto_failover_node",
    "auto_failover_maximum_reached",
    "auto_failover_other_nodes_down",
    "auto_failover_cluster_too_small",
    "auto_failover_disabled",
    "ip",
    "disk",
    "overhead",
    "ep_oom_errors",
    "ep_item_commit_failed",
    "audit_dropped_events",
    "indexer_ram_max_usage",
    "ep_clock_cas_drift_threshold_exceeded",
    "communication_issue",
    "time_out_of_sync",
    "disk_usage_analyzer_stuck",
    "history_size_warning",
    "indexer_low_resident_percentage"
  ],
  "pop_up_alerts": [
    "memory_threshold",
    "auto_failover_node",
    "auto_failover_maximum_reached",
    "auto_failover_other_nodes_down",
    "auto_failover_cluster_too_small",
    "auto_failover_disabled",
    "ip",
    "disk",
    "overhead",
    "ep_oom_errors",
    "ep_item_commit_failed",
    "audit_dropped_events",
    "indexer_ram_max_usage",
    "ep_clock_cas_drift_threshold_exceeded",
    "communication_issue",
    "time_out_of_sync",
    "disk_usage_analyzer_stuck"
  ]
}

Note that for security reasons, the pass field within the emailServer subdocument is always returned as blank, irrespective of its actual setting.

The following example sets a shorter alert list for pop-up, and none for email:

curl -v -X POST http://localhost:8091/settings/alerts -u Administrator:password \
-d pop_up_alerts=auto_failover_node,memory_threshold,indexer_ram_max_usage \
-d enabled=true

The results of the modification can be examined by means of GET /settings/alerts.

curl -v -X GET http://localhost:8091/settings/alerts -u Administrator:password | jq '.'

This returns the following:

{
  "recipients": [],
  "sender": "couchbase@localhost",
  "enabled": true,
  "emailServer": {
    "user": "",
    "pass": "",
    "host": "localhost",
    "port": 25,
    "encrypt": false
  },
  "alerts": [],
  "pop_up_alerts": [
    "memory_threshold",
    "auto_failover_node",
    "indexer_ram_max_usage"
  ]
}

This confirms that Couchbase Server is now configured to provide three pop-up alerts, and no email alerts.

The current threshold for memory management can be returned as follows:

curl -v -X GET http://localhost:8091/settings/alerts/limits -u Administrator:password | jq '.'

If successful, this returns 200 OK and an object such as the following:

{
  "historyWarningThreshold": 90,
  "lowIndexerResidentPerc": 10,
  "maxDiskUsedPerc": 90,
  "maxIndexerRamPerc": 75,
  "maxOverheadPerc": 50,
  "memoryCriticalThreshold": 95,
  "memoryNoticeThreshold": -1,
  "memoryWarningThreshold": 90
}

This shows that all parameters are at their default values. The memoryWarningThreshold can be reconfigured as follows:

curl -v -X POST http://localhost:8091/settings/alerts/limits \
-d "memoryWarningThreshold=85" \
-u Administrator:password | jq '.'

If the call is successful, the following output is returned:

{
  "historyWarningThreshold": 90,
  "lowIndexerResidentPerc": 10,
  "maxDiskUsedPerc": 90,
  "maxIndexerRamPerc": 75,
  "maxOverheadPerc": 50,
  "memoryCriticalThreshold": 95,
  "memoryNoticeThreshold": -1,
  "memoryWarningThreshold": 85
}

This confirms that the setting has been changed.