You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by bf...@apache.org on 2013/02/27 17:37:48 UTC
[23/39] git commit: refs/heads/ui-regions -
CLOUDSTACK-820-documentation for event framework
CLOUDSTACK-820-documentation for event framework
Project: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/commit/a508309e
Tree: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/tree/a508309e
Diff: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/diff/a508309e
Branch: refs/heads/ui-regions
Commit: a508309e7d87d1ab213b5f507ab5660169c202af
Parents: 9c6ced9
Author: Radhika PC <ra...@citrix.com>
Authored: Wed Feb 27 18:00:31 2013 +0530
Committer: Radhika PC <ra...@citrix.com>
Committed: Wed Feb 27 18:27:47 2013 +0530
----------------------------------------------------------------------
docs/en-US/event-framework.xml | 110 +++++++++++++++++++++++++++++++++++
docs/en-US/events.xml | 18 ++++--
2 files changed, 122 insertions(+), 6 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/a508309e/docs/en-US/event-framework.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/event-framework.xml b/docs/en-US/event-framework.xml
new file mode 100644
index 0000000..88c45c9
--- /dev/null
+++ b/docs/en-US/event-framework.xml
@@ -0,0 +1,110 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- 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.
+-->
+<section id="event-framework">
+ <title>Event Notification</title>
+ <para>Event notification framework provides a means for the Management Server components to
+ publish and subscribe to &PRODUCT; events. Event notification is achieved by implementing the
+ concept of event bus abstraction in the Management Server. An event bus is introduced in the
+ Management Server that allows the &PRODUCT;components and extension plug-ins to subscribe to the
+ events by using the Advanced Message Queuing Protocol (AMQP) client. In &PRODUCT;, a default
+ implementation of event bus is provided as a plug-in that uses the RabbitMQ AMQP client. The
+ AMQP client pushes the published events to a compatible AMQP server. Therefore all the &PRODUCT;
+ events are published to an exchange in the AMQP server. </para>
+ <para>A new event for state change, resource state change, is introduced as part of Event
+ notification framework. Every resource, such as user VM, volume, NIC, network, public IP,
+ snapshot, and template, is associated with a state machine and generates events as part of the
+ state change. That implies that a change in the state of a resource results in a state change
+ event, and the event is published in the corresponding state machine on the event bus. All the
+ &PRODUCT; events (alerts, action events, usage events) and the additional category of resource
+ state change events, are published on to the events bus.</para>
+ <formalpara>
+ <title>Use Cases</title>
+ <para>The following are some of the use cases:</para>
+ </formalpara>
+ <itemizedlist>
+ <listitem>
+ <para>Usage or Billing Engines: A third-party cloud usage solution can implement a plug-in
+ that can connects to &PRODUCT; to subscribe to &PRODUCT; events and generate usage data. The
+ usage data is consumed by their usage software.</para>
+ </listitem>
+ <listitem>
+ <para>AMQP plug-in can place all the events on the a message queue, then a AMQP message broker
+ can provide topic-based notification to the subscribers.</para>
+ </listitem>
+ <listitem>
+ <para>Publish and Subscribe notification service can be implemented as a pluggable service in
+ &PRODUCT; that can provide rich set of APIs for event notification, such as topics-based
+ subscription and notification. Additionally, the pluggable service can deal with
+ multi-tenancy, authentication, and authorization issues.</para>
+ </listitem>
+ </itemizedlist>
+ <formalpara>
+ <title>Configuration</title>
+ <para>As a &PRODUCT; administrator, perform the following one-time configuration to enable event
+ notification framework. At run time no changes can control the behaviour.</para>
+ </formalpara>
+ <orderedlist>
+ <listitem>
+ <para>Open <filename>'componentContext.xml</filename>.</para>
+ </listitem>
+ <listitem>
+ <para>Define a bean named <filename>eventNotificationBus</filename> as follows:</para>
+ <itemizedlist>
+ <listitem>
+ <para>name : Specify a name for the bean.</para>
+ </listitem>
+ <listitem>
+ <para>server : The name or the IP address of the RabbitMQ AMQP server.</para>
+ </listitem>
+ <listitem>
+ <para>port : The port on which RabbitMQ server is running.</para>
+ </listitem>
+ <listitem>
+ <para>username : The username associated with the account to access the RabbitMQ
+ server.</para>
+ </listitem>
+ <listitem>
+ <para>password : The password associated with the username of the account to access the
+ RabbitMQ server.</para>
+ </listitem>
+ <listitem>
+ <para>exchange : The exchange name on the RabbitMQ server where &PRODUCT; events are
+ published.</para>
+ <para>A sample bean is given below:</para>
+ <programlisting><bean id="eventNotificationBus" class="org.apache.cloudstack.mom.rabbitmq.RabbitMQEventBus">
+ <property name="name" value="eventNotificationBus"/>
+ <property name="server" value="127.0.0.1"/>
+ <property name="port" value="5672"/>
+ <property name="username" value="guest"/>
+ <property name="password" value="guest"/>
+ <property name="exchange" value="cloudstack-events"/>
+ </bean></programlisting>
+ <para>The <filename>eventNotificationBus</filename> bean represents the
+ <filename>org.apache.cloudstack.mom.rabbitmq.RabbitMQEventBus</filename> class.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>Restart the Management Server.</para>
+ </listitem>
+ </orderedlist>
+</section>
http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/a508309e/docs/en-US/events.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/events.xml b/docs/en-US/events.xml
index 242ff45..49ef86e 100644
--- a/docs/en-US/events.xml
+++ b/docs/en-US/events.xml
@@ -21,11 +21,17 @@
specific language governing permissions and limitations
under the License.
-->
-
<section id="events">
- <title>Events</title>
- <xi:include href="events-log.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="standard-events.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="long-running-job-events.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="event-log-queries.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <title>Events</title>
+ <para>An event is essentially a significant or meaningful change in the state of both virtual and
+ physical resources associated with a cloud environment. Events are used by monitoring systems,
+ usage and billing systems, or any other event-driven workflow systems to discern a pattern and
+ make the right business decision. In &PRODUCT; an event could be a state change of virtual or
+ psychical resources, an action performed by an user (action events), or policy based events
+ (alerts).</para>
+ <xi:include href="events-log.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="event-framework.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="standard-events.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="long-running-job-events.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="event-log-queries.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</section>