ambari-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jonathanhur...@apache.org
Subject ambari git commit: AMBARI-9980 - Create Documentation For Alerts API (jonathanhurley)
Date Mon, 09 Mar 2015 19:33:28 GMT
Repository: ambari
Updated Branches:
  refs/heads/branch-2.0.0 7f19da96c -> e207215ca


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


Project: http://git-wip-us.apache.org/repos/asf/ambari/repo
Commit: http://git-wip-us.apache.org/repos/asf/ambari/commit/e207215c
Tree: http://git-wip-us.apache.org/repos/asf/ambari/tree/e207215c
Diff: http://git-wip-us.apache.org/repos/asf/ambari/diff/e207215c

Branch: refs/heads/branch-2.0.0
Commit: e207215ca724d654ed60080a687ee9a346dbcc46
Parents: 7f19da9
Author: Jonathan Hurley <jhurley@hortonworks.com>
Authored: Sun Mar 8 22:34:20 2015 -0400
Committer: Jonathan Hurley <jhurley@hortonworks.com>
Committed: Mon Mar 9 15:33:11 2015 -0400

----------------------------------------------------------------------
 ambari-server/docs/api/v1/alert-definitions.md | 312 +++++++++++++++++++
 ambari-server/docs/api/v1/alert-dispatching.md | 326 ++++++++++++++++++++
 ambari-server/docs/api/v1/alerts.md            | 191 ++++++++++++
 ambari-server/docs/api/v1/clusters-cluster.md  |  21 +-
 ambari-server/docs/api/v1/index.md             |   9 +
 5 files changed, 851 insertions(+), 8 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/ambari/blob/e207215c/ambari-server/docs/api/v1/alert-definitions.md
----------------------------------------------------------------------
diff --git a/ambari-server/docs/api/v1/alert-definitions.md b/ambari-server/docs/api/v1/alert-definitions.md
new file mode 100644
index 0000000..fae356a
--- /dev/null
+++ b/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
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ambari/blob/e207215c/ambari-server/docs/api/v1/alert-dispatching.md
----------------------------------------------------------------------
diff --git a/ambari-server/docs/api/v1/alert-dispatching.md b/ambari-server/docs/api/v1/alert-dispatching.md
new file mode 100644
index 0000000..18881cd
--- /dev/null
+++ b/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"
+          }
+        }
+      ]
+    }
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ambari/blob/e207215c/ambari-server/docs/api/v1/alerts.md
----------------------------------------------------------------------
diff --git a/ambari-server/docs/api/v1/alerts.md b/ambari-server/docs/api/v1/alerts.md
new file mode 100644
index 0000000..f2c50a8
--- /dev/null
+++ b/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))
+        
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ambari/blob/e207215c/ambari-server/docs/api/v1/clusters-cluster.md
----------------------------------------------------------------------
diff --git a/ambari-server/docs/api/v1/clusters-cluster.md b/ambari-server/docs/api/v1/clusters-cluster.md
index 5577fe7..849aa64 100644
--- a/ambari-server/docs/api/v1/clusters-cluster.md
+++ b/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",

http://git-wip-us.apache.org/repos/asf/ambari/blob/e207215c/ambari-server/docs/api/v1/index.md
----------------------------------------------------------------------
diff --git a/ambari-server/docs/api/v1/index.md b/ambari-server/docs/api/v1/index.md
index 96abf64..c1e464c 100644
--- a/ambari-server/docs/api/v1/index.md
+++ b/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
 ----
 


Mime
View raw message