apache/cloudstack
1
0
Fork 0
mirror of https://github.com/apache/cloudstack.git synced 2025-10-26 08:42:29 +01:00
Code Issues Packages Projects Releases Wiki Activity

CLOUDSTACK-820-documentation for event framework

Browse Source
This commit is contained in:
Radhika PC 2013-02-27 18:00:31 +05:30
parent 9c6ced96c1
commit a508309e7d
2 changed files with 122 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
docs/en-US/event-framework.xml Normal file
View File

@ -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>&lt;bean id="eventNotificationBus" class="org.apache.cloudstack.mom.rabbitmq.RabbitMQEventBus"&gt;
&lt;property name="name" value="eventNotificationBus"/&gt;
&lt;property name="server" value="127.0.0.1"/&gt;
&lt;property name="port" value="5672"/&gt;
&lt;property name="username" value="guest"/&gt;
&lt;property name="password" value="guest"/&gt;
&lt;property name="exchange" value="cloudstack-events"/&gt;
&lt;/bean&gt;</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>

18
docs/en-US/events.xml
View File

@ -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>