Mailing-List: contact commits-help@eagle.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@eagle.incubator.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: qingwzhao@apache.org
To: commits@eagle.incubator.apache.org
Message-Id: <26e86a2ba3c546f19c37f837cf1bc6b9@git.apache.org>
Subject: incubator-eagle git commit: EAGLE-222 Documentation for eagle alert
 plugin mechnism
Date: Tue,  3 May 2016 02:16:58 +0000 (UTC)
archived-at: Tue, 03 May 2016 02:17:05 -0000

Repository: incubator-eagle
Updated Branches:
  refs/heads/dev 035a9f694 -> a725ea557


EAGLE-222 Documentation for eagle alert plugin mechnism

https://issues.apache.org/jira/browse/EAGLE-222

Author: Qingwen Zhao
Closes #163


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

Branch: refs/heads/dev
Commit: a725ea5578917fde915675123c5251eb6afd99b9
Parents: 035a9f6
Author: Zhao, Qingwen <qingwzhao@ebay.com>
Authored: Tue May 3 10:13:12 2016 +0800
Committer: Zhao, Qingwen <qingwzhao@ebay.com>
Committed: Tue May 3 10:13:12 2016 +0800

----------------------------------------------------------------------
 eagle-docs/images/notificationPlugin.png        | Bin 0 -> 224458 bytes
 .../alert_notification_plugin_tutorial.md       |  87 +++++++++++++++++++
 .../tutorial/application_manager_tutorial.md    |  22 ++---
 mkdocs.yml                                      |   1 +
 4 files changed, 99 insertions(+), 11 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-eagle/blob/a725ea55/eagle-docs/images/notificationPlugin.png
----------------------------------------------------------------------
diff --git a/eagle-docs/images/notificationPlugin.png b/eagle-docs/images/notificationPlugin.png
new file mode 100644
index 0000000..73a8b96
Binary files /dev/null and b/eagle-docs/images/notificationPlugin.png differ

http://git-wip-us.apache.org/repos/asf/incubator-eagle/blob/a725ea55/eagle-docs/tutorial/alert_notification_plugin_tutorial.md
----------------------------------------------------------------------
diff --git a/eagle-docs/tutorial/alert_notification_plugin_tutorial.md b/eagle-docs/tutorial/alert_notification_plugin_tutorial.md
new file mode 100644
index 0000000..7112b6c
--- /dev/null
+++ b/eagle-docs/tutorial/alert_notification_plugin_tutorial.md
@@ -0,0 +1,87 @@
+<!--
+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.
+-->
+
+### Eagle Notification Plugins
+
+[Eagle Notification Plugin](https://cwiki.apache.org/confluence/display/EAG/Alert+notification+plugin) provides an interface for users to consume Eagle alerts. When define a policy, a user can add an arbitrary number of notification plugin instances. By default, Eagle supports three types of notification: EagleStore, Kafka and Email
+
+* EagleStore: Alerts will be persisted into the underlying database via eagle. 
+	* no configuration is needed. 
+* Kafka: Alerts will flow into Kafka. Configurations are required:
+	* **kafka_broker**: <hostname:port,..., REQUIRED: The list of hostname and hostname:port> port of the server to connect to. 
+	* **topic**: kafka topic 
+* email: Alert email will be sent out. Configurations are required:
+	* **sender**: email sender address
+	* **recipients**: email recipients, multiple email address with comma separated
+	* **subject**: email subject
+	
+![notificationPlugin](/images/notificationPlugin.png)
+### Customized Notification Plugin
+
+To integrate a customized notification plugin, we must implement an interface 
+
+	public interface NotificationPlugin {
+    /**
+     * for initialization
+     * @throws Exception
+     */
+    void init(Config config, List<AlertDefinitionAPIEntity> initAlertDefs) throws  Exception;
+
+    /**
+     * Update Plugin if any change in Policy Definition
+     * @param policy to be impacted
+     * @param  notificationConfCollection
+     * @throws Exception
+     */
+    void update(String policy, List<Map<String,String>> notificationConfCollection , boolean isPolicyDelete) throws  Exception;
+
+    /**
+     * Post a notification for the given alertEntity
+     * @param alertEntity
+     * @throws Exception
+     */
+
+    void onAlert(AlertAPIEntity alertEntity) throws  Exception;
+
+    /**
+     * Returns Status of Notification Post
+     * @return
+     */
+    List<NotificationStatus> getStatusList();
+	}
+Examples: AlertKafkaPlugin, AlertEmailPlugin, and AlertEagleStorePlugin.
+
+The second and crucial step is to register the configurations of the customized plugin. In other words, we need persist the configuration template into database in order to expose the configurations to users in the front end. 
+
+Examples:
+
+ 	{
+       "prefix": "alertNotifications",
+       "tags": {
+         "notificationType": "kafka"
+       },
+       "className": "org.apache.eagle.notification.plugin.AlertKafkaPlugin",
+       "description": "send alert to kafka bus",
+       "enabled":true,
+       "fields": "[{\"name\":\"kafka_broker\",\"value\":\"sandbox.hortonworks.com:6667\"},{\"name\":\"topic\"}]"
+     }
+'fields' is the configuration for notification type 'kafka'
+
+How can we do that? [Here](https://github.com/apache/incubator-eagle/blob/master/eagle-assembly/src/main/bin/eagle-topology-init.sh) are Eagle other notification plugin configurations. Just append yours to it, and run this script when Eagle service is up. 
+
+
+

http://git-wip-us.apache.org/repos/asf/incubator-eagle/blob/a725ea55/eagle-docs/tutorial/application_manager_tutorial.md
----------------------------------------------------------------------
diff --git a/eagle-docs/tutorial/application_manager_tutorial.md b/eagle-docs/tutorial/application_manager_tutorial.md
index 5083111..4690428 100644
--- a/eagle-docs/tutorial/application_manager_tutorial.md
+++ b/eagle-docs/tutorial/application_manager_tutorial.md
@@ -51,17 +51,17 @@ After the configuration is ready, start Eagle service `bin/eagle-service.sh star
   
 #### Step 2: add topologies on UI
 1. First of all, go to admin page 
-   ![admin page](/images/appManager/admin-page.png)
-   ![admin page](/images/appManager/topology-monitor.png)
+   ![admin-page](/images/appManager/admin-page.png)
+   ![topology-monitor](/images/appManager/topology-monitor.png)
     
 2. Go to management page, and create a topology description. There are three required fields
     * name: topology name
     * type: topology type [CLASS, DYNAMIC]
     * execution entry: either the class which implement interface TopologyExecutable or eagle [DSL](https://github.com/apache/incubator-eagle/blob/master/eagle-assembly/src/main/conf/sandbox-hadoopjmx-pipeline.conf) based topology definition
-   ![admin page](/images/appManager/topology-description.png)
+   ![topology-description](/images/appManager/topology-description.png)
    
 3. Back to monitoring page, and choose the site/application to deploy the topology 
-   ![admin page](/images/appManager/topology-execution.png)
+   ![topology-execution](/images/appManager/topology-execution.png)
    
 4. Go to site page, and edit site->application and add some new configurations. Blow are some example configurations for [site=sandbox, applicatoin=hbaseSecurityLog]
    `These configurations have a higher priority than those in eagle-scheduler.conf`
@@ -94,16 +94,16 @@ After the configuration is ready, start Eagle service `bin/eagle-service.sh star
            app.eagleProps.eagleService.port=9099
            app.eagleProps.eagleService.username=admin
            app.eagleProps.eagleService.password=secret
-   ![admin page](/images/appManager/topology-configuration-1.png)
-   ![admin page](/images/appManager/topology-configuration-2.png)
+   ![topology-configuration-1](/images/appManager/topology-configuration-1.png)
+   ![topology-configuration-2](/images/appManager/topology-configuration-2.png)
    
 5. Go to monitoring page, and start topologies
-   ![admin page](/images/appManager/start-topology-1.png)
-   ![admin page](/images/appManager/start-topology-2.png)
+   ![start-topology-1](/images/appManager/start-topology-1.png)
+   ![start-topology-2](/images/appManager/start-topology-2.png)
    
 6. stop topologies on monitoring page
-   ![admin page](/images/appManager/stop-topology-1.png)
-   ![admin page](/images/appManager/stop-topology-2.png)
-   ![admin page](/images/appManager/stop-topology-3.png)
+   ![stop-topology-1](/images/appManager/stop-topology-1.png)
+   ![stop-topology-2](/images/appManager/stop-topology-2.png)
+   ![stop-topology-3](/images/appManager/stop-topology-3.png)
 
  
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-eagle/blob/a725ea55/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index c07ed4a..c3a150b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -56,5 +56,6 @@ pages:
 - Tutorial:
    - Getting started with Eagle: tutorial/getting_started_with_eagle.md
    - Application Manager Tutorial: tutorial/application_manager_tutorial.md
+   - Alert Notification Plugin tutorial: tutorial/alert_notification_plugin_tutorial.md
 - User Guide:
    - Installation: userguide/installation.md