Setting Alerts
- reference
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> -d memcachedSystemConnectionWarningThreshold=<integer> -d memcachedUserConnectionWarningThreshold=<integer> curl -X POST http://<ip-address-or-domain-name>:8091/settings/alert/sendTestEmail -u <username>:<password>
-
username
andpassword
. 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 iscouchbase@localhost
. -
recipients
. A list of comma-separated email addresses of the intended recipients. This parameter is optional. The default value isroot@localhost
. -
emailHost
. The IP address or domain name of the email server to dispatch the alerts. This parameter is optional. The default value islocalhost
. -
emailPort
. The port that will be used by the email server. This parameter is optional. The default value is25
. -
emailEncrypt
. Determines whether emails should be dispatched in encrypted form: the value must betrue
orfalse
(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, whenenabled
istrue
. 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, whenenabled
istrue
. 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 betrue
orfalse
(the default). If alerts are enabled, any alert that appears in the list that is passed as the value ofalerts
orpop_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 ofhistoryWarningThreshold
must be an integer that represents a percentage: the default value is90
. 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 oflowIndexerResidentPerc
. The default value is10
. -
maxDiskUsedPerc
,maxIndexerRamPerc
, andmaxOverheadPerc
. The maximum percentages for disk usage, memory consumption by the Index Service, and overhead. Values must be between0
and100
. -
memoryNoticeThreshold
,memoryWarningThreshold
, andmemoryCriticalThreshold
. Thresholds for memory-usage. These are all disabled until thememory_threshold
alert is enabled — for email or for pop-up display, or for both — by means ofPOST /settings/alerts
(see Available Alerts for the full list of alerts). Note that even whenmemory_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 between1
and100
: 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 ofPOST /settings/alerts/limits
; and their values are retrieved by means ofGET /settings/alerts/limits
.The thresholds are intended to be assigned values in ascending order; with
memoryNoticeThreshold
the lowest, andmemoryCriticalThreshold
the highest. The default values are, formemoryNoticeThreshold
-1
(meaning disabled), formemoryWarningThreshold
90
, and formemoryCriticalThreshold
95
.
-
memcachedSystemConnectionWarningThreshold
. Trigger thememcached_connections
alert if the number ofsystem
connections in use exceeds the given percentage of connections available. (E.g., set this value to90
to trigger an alert if the system connections used by the data service exceed 90% of the connections available.)If the node exceeds 90% of the available system connections, then please contact Couchbase Support. -
memcachedUserConnectionWarningThreshold
. Trigger thememcached_connections
alert if the number ofuser
connections in use exceeds the given percentage of connections available. (E.g., if this value is set to90
, the system will trigger an alert if the number of user connections used by the data service exceeds 90% of the available connections.)
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", "memcached_connections" ] }
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.
See Also
Information on managing alerts by means of the UI and CLI is provided in Available Alerts. An overview of memory management is provided in Memory.