AMBARI-9980 - Create Documentation For Alerts API (jonathanhurley)

ambari-server/docs/api/v1/alert-definitions.md

@@ -0,0 +1,312 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+# Alert Definitions
+Definitions are the templates that are used to distribute alerts to the appropriate Ambari agents. They govern the type of alert, the threshold values, and the information to be used when notifying a target. A single definition can be distributed to more than one host in order to produce multiple instances of an alert. 
+
+### Concepts
+Each definition contains common information, such as a unique identifier, service, and component. Beyond this, definitions declare a type with each type having its own distinct properties. 
+
+##### Common Properties
+
+- id
+- name
+- label
+- cluster_name
+- service_name
+- component_name
+- source
+
+#### Types
+###### SCRIPT
+Script definitions defer all functionality to a Python script accessible to the Ambari agents from a specified relative or absolute path.
+
+        "source" : {
+          "path" : "HDFS/2.1.0.2.0/package/alerts/alert_ha_namenode_health.py",
+          "type" : "SCRIPT"
+        }
+
+###### METRIC
+METRIC source fields are used to define JMX endpoints that can be queried for values. The `source/reporting` and `jmx/value` fields are parameterized to match the `property_list` specified.
+
+        "source" : {
+          "jmx" : {
+            "property_list" : [
+              "java.lang:type=OperatingSystem/SystemCpuLoad",
+              "java.lang:type=OperatingSystem/AvailableProcessors"
+            ],
+            "value" : "{0} * 100"
+          },
+          "reporting" : {
+            "ok" : {
+              "text" : "{1} CPU, load {0:.1%}"
+            },
+            "warning" : {
+              "text" : "{1} CPU, load {0:.1%}",
+              "value" : 200.0
+            },
+            "critical" : {
+              "text" : "{1} CPU, load {0:.1%}",
+              "value" : 250.0
+            },
+            "units" : "%"
+          },
+          "type" : "METRIC",
+          "uri" : {
+            "http" : "{{hdfs-site/dfs.namenode.http-address}}",
+            "https" : "{{hdfs-site/dfs.namenode.https-address}}",
+            "https_property" : "{{hdfs-site/dfs.http.policy}}",
+            "https_property_value" : "HTTPS_ONLY",
+            "default_port" : 0.0,
+            "high_availability" : {
+              "nameservice" : "{{hdfs-site/dfs.nameservices}}",
+              "alias_key" : "{{hdfs-site/dfs.ha.namenodes.{{ha-nameservice}}}}",
+              "http_pattern" : "{{hdfs-site/dfs.namenode.http-address.{{ha-nameservice}}.{{alias}}}}",
+              "https_pattern" : "{{hdfs-site/dfs.namenode.https-address.{{ha-nameservice}}.{{alias}}}}"
+            }
+          }
+        }
+        
+###### WEB
+WEB definitions are similar in function to PORT definitions. However, instead of checking for TCP connectivity, they also verify that a proper HTTP response code was returned.
+
+        "source" : {
+          "reporting" : {
+            "ok" : {
+              "text" : "HTTP {0} response in {2:.3f} seconds"
+            },
+            "warning" : {
+              "text" : "HTTP {0} response in {2:.3f} seconds"
+            },
+            "critical" : {
+              "text" : "Connection failed to {1}: {3}"
+            }
+          },
+          "type" : "WEB",
+          "uri" : {
+            "http" : "{{hdfs-site/dfs.namenode.http-address}}",
+            "https" : "{{hdfs-site/dfs.namenode.https-address}}",
+            "https_property" : "{{hdfs-site/dfs.http.policy}}",
+            "https_property_value" : "HTTPS_ONLY",
+            "kerberos_keytab" : "{{hdfs-site/dfs.web.authentication.kerberos.keytab}}",
+            "kerberos_principal" : "{{hdfs-site/dfs.web.authentication.kerberos.principal}}",
+            "default_port" : 0.0,
+            "high_availability" : {
+              "nameservice" : "{{hdfs-site/dfs.nameservices}}",
+              "alias_key" : "{{hdfs-site/dfs.ha.namenodes.{{ha-nameservice}}}}",
+              "http_pattern" : "{{hdfs-site/dfs.namenode.http-address.{{ha-nameservice}}.{{alias}}}}",
+              "https_pattern" : "{{hdfs-site/dfs.namenode.https-address.{{ha-nameservice}}.{{alias}}}}"
+            }
+          }
+        }
+
+###### PORT
+PORT definitions are used to check TCP connectivity to a remote endpoint.
+
+       "source" : {
+          "default_port" : 2181,
+          "reporting" : {
+            "ok" : {
+              "text" : "TCP OK - {0:.3f}s response on port {1}"
+            },
+            "warning" : {
+              "text" : "TCP OK - {0:.3f}s response on port {1}",
+              "value" : 1.5
+            },
+            "critical" : {
+              "text" : "Connection failed: {0} to {1}:{2}",
+              "value" : 5.0
+            }
+          },
+          "type" : "PORT",
+          "uri" : "{{core-site/ha.zookeeper.quorum}}"
+        }
+      }
+
+#### Structures & Concepts
+- `uri` Definition types that contain a URI can depend on any number of valid subproperties. In some cases, the URI may be very simple and only include a single port. In other scenarios, the URI may be more complex and include properties for plaintext, SSL, and secure endpoints protected by Kerberos.
+
+    - http - a property that contains the plaintext endpoint to test
+    - https - a property that contains the SSL endpoint to test
+    - https_property - a property that contains the value which can be used to determine if the component is SSL protected
+    - http_property_value - a constant value to compare with `https_property` in order to determine if the component is protected by SSL
+    - kerberos_keytab - a property that contains the Kerberos keytab if security is enabled
+    - kerberos_principal - a property that contains the Kerberos principal if security is enabled
+    - default_port - a default port which can be used if none of the above properties can be realized
+    - high_availability - a structure that contains a way to dynamically build properties which contain the endpoints to use when the components are running in HA mode
+    
+<p/>
+
+- `reporting` A structure that defines the thresholds and text to use when determining the state for an alert. `ok` is always a required element, however only a single `warning` or `critical` element is needed. Some alerts may only have two states (such as `OK` and `CRITICAL`) and will bypass the need for a `warning` element.
+
+<p/>
+
+- `default_port` A URI, host, or integer that represents a fallback value to use if none of the other specified properties can be realized.
+
+### API Summary
+
+##### Create
+    POST api/v1/clusters/<cluster>/alert_definitions
+    
+    {
+      "AlertDefinition" : {
+        "service_name" : "YARN",      
+        "component_name" : "RESOURCEMANAGER",
+        "enabled" : true,
+        "interval" : 1,
+        "label" : "Example YARN ResourceManager Alert",
+        "name" : "example_yarn_rm_alert",
+        "scope" : "ANY",
+        "source" : {
+          "default_port" : 8050,
+          "reporting" : {
+            "ok" : {
+              "text" : "TCP OK - {0:.4f} response on port {1}"
+            },
+           "warning" : {
+              "text" : "TCP OK - {0:.3f}s response on port {1}",
+              "value" : 1.5
+            },
+            "critical" : {
+              "text" : "Connection failed: {0} on host {1}:{2}",
+              "value" : 5.0
+            }
+          },
+          "type" : "PORT",
+          "uri" : "{{yarn-site/yarn.resourcemanager.address}}"
+        }
+      }
+    }    
+
+##### Update
+When updating an existing definition, then entire structure is not required. A partial request is allowed and will only change the properties that were supplied. Properties that are omitted are considered unchanged.
+
+    PUT api/v1/clusters/<cluster>/alert_definitions/<definition-id>
+    
+    {
+      "AlertDefinition" : {
+        "interval" : 10,
+          "uri" : "{{yarn-site/yarn.resourcemanager.address.foo}}"
+        }
+      }
+    }
+        
+
+##### Delete
+    DELETE api/v1/clusters/<cluster>/alert_definitions/<definition-id>
+
+##### Querying
+Definitions are always retrieved from the cluster endpoint since each cluster can have its own assortment of alerts defined. 
+
+###### Request
+    GET api/v1/clusters/<cluster>/alert_definitions    
+    
+###### Response
+    {
+      "href" : "http://<server>/api/v1/clusters/<cluster>/alert_definitions",
+      "items" : [
+        {
+          "href" : "http://<server>/api/v1/clusters/<cluster>/alert_definitions/1",
+          "AlertDefinition" : {
+            "cluster_name" : "<cluster>",
+            "id" : 1,
+            "label" : "History Server Web UI",
+            "name" : "mapreduce_history_server_webui"
+          }
+        },
+        {
+          "href" : "http://<server>/api/v1/clusters/<cluster>/alert_definitions/2",
+          "AlertDefinition" : {
+            "cluster_name" : "<cluster>",
+            "id" : 2,
+            "label" : "History Server Process",
+            "name" : "mapreduce_history_server_process"
+          }
+        },
+        ...
+      ]
+    }
+
+Querying for definitions accepts the same predicates and syntax as other areas of the REST API. For example, to query for all definitions for `NAMENODE` that are of type `WEB` and `METRIC` the following query can be used.
+
+###### Request
+    GET api/v1/clusters/<cluster>/alert_definitions?AlertDefinition/component_name=NAMENODE&AlertDefinition/source/type.in(WEB,METRIC)
+
+###### Response
+    {
+      "href" : "http://<server>/api/v1/clusters/<cluster>/alert_definitions?AlertDefinition/component_name=NAMENODE&AlertDefinition/source/type.in(WEB,METRIC)",
+      "items" : [
+        {
+          "href" : "http://<server>/api/v1/clusters/<cluster>/alert_definitions/14",
+          "AlertDefinition" : {
+            "cluster_name" : "<cluster>",
+            "component_name" : "NAMENODE",
+            "id" : 14,
+            "label" : "NameNode Host CPU Utilization",
+            "name" : "namenode_cpu",
+            "source" : {
+              "jmx" : {
+                "property_list" : [
+                  "java.lang:type=OperatingSystem/SystemCpuLoad",
+                  "java.lang:type=OperatingSystem/AvailableProcessors"
+                ],
+                "value" : "{0} * 100"
+              },
+              "reporting" : {
+                "ok" : {
+                  "text" : "{1} CPU, load {0:.1%}"
+                },
+                "warning" : {
+                  "text" : "{1} CPU, load {0:.1%}",
+                  "value" : 200.0
+                },
+                "critical" : {
+                  "text" : "{1} CPU, load {0:.1%}",
+                  "value" : 250.0
+                },
+                "units" : "%"
+              },
+              "type" : "METRIC",
+              "uri" : {
+                "http" : "{{hdfs-site/dfs.namenode.http-address}}",
+                "https" : "{{hdfs-site/dfs.namenode.https-address}}",
+                "https_property" : "{{hdfs-site/dfs.http.policy}}",
+                "https_property_value" : "HTTPS_ONLY",
+                "default_port" : 0.0,
+                "high_availability" : {
+                  "nameservice" : "{{hdfs-site/dfs.nameservices}}",
+                  "alias_key" : "{{hdfs-site/dfs.ha.namenodes.{{ha-nameservice}}}}",
+                  "http_pattern" : "{{hdfs-site/dfs.namenode.http-address.{{ha-nameservice}}.{{alias}}}}",
+                  "https_pattern" : "{{hdfs-site/dfs.namenode.https-address.{{ha-nameservice}}.{{alias}}}}"
+                }
+              }
+            }
+          }
+        },
+        ...
+      ]
+    }
+    
+##### Immediate Execution
+Definitions can be forcible triggered to run outside of their normally scheduled timeframe. This can be useful when verifying that an alert has changed state without waiting for it to run on its own.
+
+###### Request
+Using the `run_now` directive, a definition can be scheduled to run immediately on all hosts where it is distributed.
+
+    PUT http://<server>/api/v1/clusters/<cluster>/alert_definitions/<definition-id>?run_now=true
+    
+###### Response
+    HTTP 200 OK

ambari-server/docs/api/v1/alert-dispatching.md

@@ -0,0 +1,326 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+# Alert Dispatching
+
+### Concepts
+
+##### Groups
+Alert definitions can be combined into groups. There is a default group for each service deployed in Ambari. These default groups contain each of the definitions that exist for that service. When a new definition is created for a given service, it is automatically added to the default group for that service.
+
+To create custom groupings, any number of definitions from any service can be mixed together.
+
+##### Targets
+Targets are used to notify an interested party that an alert instance has changed state. There are currently two supported target types:
+
+* Email (SMTP)
+* Simple Network Management Protocol (SNMP)
+    * SNMPv1
+    * SNMPv2c
+    * SNMPv3
+    
+Any number of targets can be associated with an alert group (a grouping of definitions). When a definition in the group changes state, all associated targets will be notified. 
+
+There is also a `global` alert target which can be used as a way to produce notifications for any alert defined in Ambari. These `global` targets are never associated with any groups; they apply to all groups and all definitions.
+
+##### Notices
+Once an alert has changed state, Ambari will determine if there are any targets that should receive a notification of the state change. These notifications, or notices, are created with an initial status of `PENDING` and will transition either to `DELIVERED` or `FAILED` once the proper dispatcher has attemped to process the notice. Dispatchers can attempt to aggregate any `PENDING` notices into a single outbound notification.
+
+### API Summary
+
+#### Groups
+
+##### Create Request
+A group can be created with just a name and then updated later with any of its valid properties. 
+
+    POST api/v1/clusters/<cluster>/alert_groups
+    
+    {
+      "AlertGroup": {
+        "name": "Demo Group"
+      }
+    }
+
+Or it can be created with all valid properties. In this example, a group is being associated with 2 existing targets and 3 existing definitions.
+
+    POST api/v1/clusters/<cluster>/alert_groups
+
+    {
+      "AlertGroup": {
+        "name": "Demo Group",
+        "targets": [1, 2],
+        "definitions": [7, 9, 14]
+      }
+    }
+
+
+##### Update Request
+    POST api/v1/clusters/<cluster>/alert_groups/<group-id>
+
+    {
+      "AlertGroup": {
+        "name": "Demo Group",
+        "targets": [1, 2, 3],
+        "definitions": [7, 9, 14, 21, 28, 29, 30]
+      }
+    }
+    
+##### Delete Request
+    DELETE api/v1/clusters/<cluster>/alert_groups/<group-id>
+    
+##### Query Request
+    GET api/v1/clusters/<cluster>/alert_groups
+
+##### Query Response
+    {
+      "href" : "http://<server>/api/v1/clusters/<cluster>/alert_groups",
+      "items" : [
+        {
+          "href" : "http://<server>/api/v1/clusters/<cluster>/alert_groups/1",
+          "AlertGroup" : {
+            "cluster_name" : "<cluster>",
+            "id" : 1,
+            "name" : "TEZ"
+          }
+        },
+        {
+          "href" : "http://<server>/api/v1/clusters/<cluster>/alert_groups/2",
+          "AlertGroup" : {
+            "cluster_name" : "<cluster>",
+            "id" : 2,
+            "name" : "MAPREDUCE2"
+          }
+        },
+        ...
+      ]
+    }
+
+##### Query Request
+    GET api/v1/clusters/<cluster>/alert_groups/<group-id>
+
+##### Query Response
+Each group contains information about the definitions and targets associated with it.
+
+    {
+      "href" : "http://<server>/api/v1/clusters/<cluster>/alert_groups/2?fields=*",
+      "AlertGroup" : {
+        "cluster_name" : "<cluster>",
+        "default" : true,
+        "definitions" : [
+          {
+            "name" : "mapreduce_history_server_webui",
+            "label" : "History Server Web UI",
+            "description" : "This host-level alert is triggered if the History Server Web UI is unreachable.",
+            "enabled" : true,
+            "service_name" : "MAPREDUCE2",
+            "component_name" : "HISTORYSERVER",
+            "id" : 1,
+            "source_type" : "WEB"
+          },
+          ...
+        ],
+        "id" : 3,
+        "name" : "MAPREDUCE2",
+        "targets" : [
+          {
+            "name" : "Administrators",
+            "id" : 1,
+            "description" : "The Admins",
+            "global" : false,
+            "notification_type" : "EMAIL"
+          }
+        ]
+      }
+    }
+
+
+#### Targets
+Each target type has its own set of properties that are used to configure the backend dispatcher. These properties are typically not shared between targets except for the following global properties:
+
+* ambari.dispatch.credential.username - an optional property for specifying the username needed for the dispatcher in order to relay the notification.
+* ambari.dispatch.credential.password - an optional property for specifying the password needed for the dispatcher in order to relay the notification.
+* ambari.dispatch.recipients - an array of strings representing each recipient to receive an alert notification. This is a free-form string that the backend dispatcher can understand. For example, with an `EMAIL` target, this would be a list of email addresses.
+
+The following is a list of target types and the valid properties that they accept:
+
+* Email - any JavaMail property
+* SNMP
+    * ambari.dispatch.snmp.oids.body
+    * ambari.dispatch.snmp.oids.subject
+    * ambari.dispatch.snmp.oids.trap
+    * ambari.dispatch.snmp.port
+    * ambari.dispatch.snmp.version
+    * ambari.dispatch.snmp.community
+    * ambari.dispatch.snmp.security.username
+    * ambari.dispatch.snmp.security.auth.passphrase
+    * ambari.dispatch.snmp.security.priv.passphrase
+    * ambari.dispatch.snmp.security.level
+
+
+##### Create Request
+In this example, several JavaMail properties are specified in order for this target to connect and authenticate with the SMTP relay. If the target was not global, any existing groups could be included as well when creating the target.
+
+    POST api/v1/alert_targets
+    
+    {
+      "AlertTarget": {
+        "name": "Administrators",
+        "description": "The Admins",
+        "notification_type": "EMAIL",
+        "global": true,
+        "properties":{
+          "ambari.dispatch.credential.username":"ambari",
+          "ambari.dispatch.credential.password":"password",
+          "ambari.dispatch.recipients":["ambari@relay.ambari.apache.org"],
+          "mail.smtp.host":"relay.ambari.apache.org",
+          "mail.smtp.port":"25",
+          "mail.smtp.auth":"true",
+          "mail.smtp.starttls.enable":"false",
+          "mail.smtp.from":"ambari@relay.ambari.apache.org"
+        }
+      }
+    }
+
+##### Update Request
+Alert targets can be updated with a partial body. Properties which are not specified are assumed to not change. 
+
+    PUT api/v1/alert_targets/<target-id>
+    
+    {
+      "AlertTarget": {
+        "alert_states": ["OK", "WARNING"]
+      }
+    }
+
+##### Delete Request
+    DELETE api/v1/alert_targets/<target-id>
+        
+##### Query Request
+Targets are not associated with any aspect of a cluster. Therefore their endpoint is defined without any cluster scoping. This allows the same target to be reused for other clusters managed by Ambari.
+
+    GET api/v1/alert_targets
+
+##### Query Response
+The target from the query has the following attributes:
+
+* It is associated with the HDFS alert group
+* It will trigger for any of the alert states
+<!-- --> 
+
+    GET api/v1/alert_targets
+    
+    {
+      "href" : "http://<server>/api/v1/alert_targets?fields=*",
+      "items" : [
+        {
+          "href" : "http://<server>/api/v1/alert_targets/1",
+          "AlertTarget" : {
+            "alert_states" : [
+              "OK",
+              "CRITICAL",
+              "UNKNOWN",
+              "WARNING"
+            ],
+            "description" : "The Admins",
+            "global" : false,
+            "groups" : [
+              {
+                "name" : "HDFS",
+                "id" : 3,
+                "default" : true,
+                "cluster_id" : 2
+              }
+            ],
+            "id" : 1,
+            "name" : "Administrators",
+            "notification_type" : "EMAIL",
+            "properties" : {
+              "mail.smtp.from" : "ambari@relay.ambari.apache.org",
+              "ambari.dispatch.credential.username" : "ambari",
+              "mail.smtp.host" : "relay.ambari.apache.org",
+              "mail.smtp.port" : "25",
+              "mail.smtp.auth" : "true",
+              "ambari.dispatch.credential.password" : "password",
+              "ambari.dispatch.recipients" : [
+                "ambari@relay.ambari.apache.org"
+              ],
+              "mail.smtp.starttls.enable" : "false"
+            }
+          }
+        }
+      ]
+    }
+    
+#### Validation
+Before a target is created, it is possible to have Ambari validate whether the properties being specified are correct. Ambari will attempt to execise the target and return a response with the validation information.
+
+###### Request
+Use the `validate_config` directive to have Ambari connect to the backend dispatcher in order to verify the the target's properties are valid.
+
+    POST api/v1/alert_targets?validate_config=true
+    
+    {
+      "AlertTarget": {
+        "name": "Administrators",
+        "description": "The Admins",
+        "notification_type": "EMAIL",
+        "global": true,
+        "properties":{
+          "ambari.dispatch.credential.username":"ambari",
+          "ambari.dispatch.credential.password":"password",
+          "ambari.dispatch.recipients":["ambari@invalid.ambari.apache.org"],
+          "mail.smtp.host":"invalid.ambari.apache.org",
+          "mail.smtp.port":"25",
+          "mail.smtp.auth":"true",
+          "mail.smtp.starttls.enable":"false",
+          "mail.smtp.from":"ambari@invalid.ambari.apache.org"
+        }
+      }
+    }    
+    
+###### Response
+    HTTP 400 Bad Request
+    
+    {
+      "status" : 400,
+      "message" : "Invalid config: Couldn't connect to host, port: invalid.ambari.apache.org, 25; timeout -1"
+    }    
+
+#### Notices
+Notices are read-only and are produced by Ambari in response to alerting events. They are used to maintain an audit trail of the outbound notifications and whether they were successfully delivered to the backend dispatcher.
+
+##### Request
+    GET api/v1/clusters/<cluster>/alert_notices
+    
+##### Response
+    {
+      "href" : "http://<server>/api/v1/clusters/<server>/alert_notices?fields=*",
+      "items" : [
+        {
+          "href" : "http://<server>/api/v1/clusters/<cluster>/alert_notices/1",
+          "AlertNotice" : {
+            "cluster_name" : "<cluster>",
+            "history_id" : 227,
+            "id" : 1,
+            "notification_state" : "DELIVERED",
+            "service_name" : "ZOOKEEPER",
+            "target_id" : 3,
+            "target_name" : "Administrators",
+            "uuid" : "fef28294-bb3a-4186-b62c-1a060fa75927"
+          }
+        }
+      ]
+    }

ambari-server/docs/api/v1/alerts.md

@@ -0,0 +1,191 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+# Alerts
+Alert instances are divided into two different endpoints. There's one endpoint for history where all of the state changes for a definition are recorded. Another endpoint is used for the current state of all alert instances in the cluster.
+
+Historical events are created when an alert's state changes. As alerts are collected from Ambari agents, timestamp and text is updated on the most recent alert instance.
+
+## Current Alerts
+Alert instances are read-only. They support the full predicate, sorting, and pagination syntax of the Ambari REST API.
+
+#### Querying
+Current alerts can be exposed on the following resource endpoints:
+
+##### Cluster Request
+    GET api/v1/clusters/<cluster>/alerts
+    
+##### Service Request
+    GET api/v1/clusters/<cluster>/services/<service>/alerts
+
+##### Host Request
+    GET api/v1/clusters/<cluster>/hosts/<host>/alerts
+    
+##### Alert Response
+    {
+      "href" : "http://<server>/api/v1/clusters/<cluster>/alerts?fields=*",
+      "items" : [
+        {
+          "href" : "http://<server>/api/v1/clusters/<cluster>/alerts/2",
+          "Alert" : {
+            "cluster_name" : "<cluster>",
+            "component_name" : "AMBARI_AGENT",
+            "definition_id" : 39,
+            "definition_name" : "ambari_agent_disk_usage",
+            "host_name" : "<host>",
+            "id" : 2,
+            "instance" : null,
+            "label" : "Ambari Agent Disk Usage",
+            "latest_timestamp" : 1425704842163,
+            "maintenance_state" : "OFF",
+            "original_timestamp" : 1425600467615,
+            "scope" : "HOST",
+            "service_name" : "AMBARI",
+            "state" : "OK",
+            "text" : "Capacity Used: [0.74%, 3.9 GB], Capacity Total: [525.3 GB]"
+          }
+        },
+        ...
+      ]
+    }
+    
+
+
+#### Advanced Queries
+
+##### Data Formatters
+* Summary - provides a count of all alert states, including how many are in maintenance mode. 
+* Grouped Summary - provides a count of all alert states grouped by definition, including how many are in maintenance mode. Each definition group will also contain the most recent text for each state.
+
+###### Summary Request
+    GET api/v1/clusters/<cluster>/alerts?format=summary
+
+###### Summary Response
+    {
+      "href" : "http://<server>/api/v1/clusters/<cluster>/alerts?format=summary",
+      "alerts_summary" : {
+        "OK" : {
+          "count" : 66,
+          "original_timestamp" : 1425699364098,
+          "maintenance_count" : 0
+        },
+        "WARNING" : {
+          "count" : 0,
+          "original_timestamp" : 0,
+          "maintenance_count" : 0
+        },
+        "CRITICAL" : {
+          "count" : 0,
+          "original_timestamp" : 0,
+          "maintenance_count" : 0
+        },
+        "UNKNOWN" : {
+          "count" : 0,
+          "original_timestamp" : 0,
+          "maintenance_count" : 0
+        }
+      }
+    }
+
+###### Grouped Summary Request
+    GET api/v1/clusters/<cluster>/alerts?format=groupedSummary
+
+###### Grouped Summary Response
+    {
+      "href" : "http://<server>/api/v1/clusters/<cluster>/alerts?format=groupedSummary",
+      "alerts_summary_grouped" : [
+        {
+          "definition_id" : 30,
+          "definition_name" : "yarn_resourcemanager_webui",
+          "summary" : {
+            "OK" : {
+              "count" : 1,
+              "original_timestamp" : 1425603503227,
+              "maintenance_count" : 0,
+              "latest_text" : "HTTP 200 response in 0.000 seconds"
+            },
+            "WARNING" : {
+              "count" : 0,
+              "original_timestamp" : 0,
+              "maintenance_count" : 0
+            },
+            "CRITICAL" : {
+              "count" : 0,
+              "original_timestamp" : 0,
+              "maintenance_count" : 0
+            },
+            "UNKNOWN" : {
+              "count" : 0,
+              "original_timestamp" : 0,
+              "maintenance_count" : 0
+            }
+          }
+        },
+        ...
+      ]
+    }
+
+##### All `CRITICAL` and `WARNING` Alerts, Sorted by State
+    GET api/v1/clusters/<cluster>/alerts?fields=*&Alert/state.in(WARNING,CRITICAL)&sortBy=Alert/state
+
+
+## Alert History
+Historical entries are read-only. They support the full predicate, sorting, and pagination syntax of the Ambari REST API.
+
+#### Querying
+History can be exposed on the following resource endpoints:
+
+##### Cluster Request
+    GET api/v1/clusters/<cluster>/alert_history
+    
+##### Service Request
+    GET api/v1/clusters/<cluster>/services/<service>/alert_history
+
+##### Host Request
+    GET api/v1/clusters/<cluster>/hosts/<host>/alert_history
+
+##### Response
+    {
+      "href" : "http://<server>/api/v1/clusters/<cluster>/alert_history?fields=*",
+      "items" : [
+        {
+          "href" : "http://<server>/api/v1/clusters/<cluster>/alert_history/159",
+          "AlertHistory" : {
+            "cluster_name" : "<cluster>",
+            "component_name" : "ZOOKEEPER_SERVER",
+            "definition_id" : 37,
+            "definition_name" : "zookeeper_server_process",
+            "host_name" : "c6403.ambari.apache.org",
+            "id" : 159,
+            "instance" : null,
+            "label" : "ZooKeeper Server Process",
+            "service_name" : "ZOOKEEPER",
+            "state" : "OK",
+            "text" : "TCP OK - 0.000s response on port 2181",
+            "timestamp" : 1425603185086
+          }
+        },
+        ...
+      ]
+    }
+
+#### Advanced Queries
+##### `WARNING` alerts, 100 per page, starting at 1
+    GET api/v1/clusters/<cluster>/alert_history?(AlertHistory/state=WARNING)&fields=*&from=start&page_size=100
+
+##### All alerting events for HDFS and YARN
+    GET api/v1/clusters/c1/alert_history?(AlertHistory/service_name.in(HDFS,YARN))
+        

ambari-server/docs/api/v1/clusters-cluster.md

@@ -133,14 +133,19 @@ Get information for the cluster "cluster001".
 			}
 		}
 	},
-	"alerts" : {
-		"summary" : {
-			"CRITICAL" : 1,
-			"OK" : 2,
-			"PASSIVE" : 0,
-			"WARNING" : 0
-		}
-	},
+    "alerts_summary" : {
+      "CRITICAL" : 0,
+      "MAINTENANCE" : 0,
+      "OK" : 65,
+      "UNKNOWN" : 0,
+      "WARNING" : 0
+    },
+    "alerts_summary_hosts" : {
+      "CRITICAL" : 0,
+      "OK" : 3,
+      "UNKNOWN" : 0,
+      "WARNING" : 0
+    },
 	"requests" : [
 		{
 			"href" : "http://your.ambari.server/api/v1/clusters/cluster001/requests/304",

ambari-server/docs/api/v1/index.md

@@ -353,6 +353,15 @@ Rolling upgrades check resources store information about successful/unsuccessful
 #### upgrades
 [Upgrade Resources](upgrades.md)
 
+#### alerts
+Alert resources contain the relationships between definitions, history, and the dispatching of outbound notifications. Ambari leverages its own alert framework in order to monitor a service, component, or host and produce notifications to interested parties.
+
+- [Alert Definitions](alert-definitions.md) Definitions are the templates that are used to distribute alerts to the appropriate Ambari agents. They govern the type of alert, the threshold values, and the information to be used when notifying a target.
+
+- [Alert Dispatching](alert-dispatching.md) Dispatching involves creating groups of alert definitions and adding notification targets to those groups.
+
+- [Alert History](alerts.md) The current state of an alert and all of its historical events are available for querying.
+
 Partial Response
 ----