Skip to content

Commit a508309

Browse files
author
Radhika PC
committed
CLOUDSTACK-820-documentation for event framework
1 parent 9c6ced9 commit a508309

2 files changed

Lines changed: 122 additions & 6 deletions

File tree

‎docs/en-US/event-framework.xml‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
<?xml version='1.0' encoding='utf-8' ?>
2+
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
3+
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
4+
%BOOK_ENTITIES;
5+
]>
6+
7+
<!-- Licensed to the Apache Software Foundation (ASF) under one
8+
or more contributor license agreements. See the NOTICE file
9+
distributed with this work for additional information
10+
regarding copyright ownership. The ASF licenses this file
11+
to you under the Apache License, Version 2.0 (the
12+
"License"); you may not use this file except in compliance
13+
with the License. You may obtain a copy of the License at
14+
http://www.apache.org/licenses/LICENSE-2.0
15+
Unless required by applicable law or agreed to in writing,
16+
software distributed under the License is distributed on an
17+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18+
KIND, either express or implied. See the License for the
19+
specific language governing permissions and limitations
20+
under the License.
21+
-->
22+
<section id="event-framework">
23+
<title>Event Notification</title>
24+
<para>Event notification framework provides a means for the Management Server components to
25+
publish and subscribe to &PRODUCT; events. Event notification is achieved by implementing the
26+
concept of event bus abstraction in the Management Server. An event bus is introduced in the
27+
Management Server that allows the &PRODUCT;components and extension plug-ins to subscribe to the
28+
events by using the Advanced Message Queuing Protocol (AMQP) client. In &PRODUCT;, a default
29+
implementation of event bus is provided as a plug-in that uses the RabbitMQ AMQP client. The
30+
AMQP client pushes the published events to a compatible AMQP server. Therefore all the &PRODUCT;
31+
events are published to an exchange in the AMQP server. </para>
32+
<para>A new event for state change, resource state change, is introduced as part of Event
33+
notification framework. Every resource, such as user VM, volume, NIC, network, public IP,
34+
snapshot, and template, is associated with a state machine and generates events as part of the
35+
state change. That implies that a change in the state of a resource results in a state change
36+
event, and the event is published in the corresponding state machine on the event bus. All the
37+
&PRODUCT; events (alerts, action events, usage events) and the additional category of resource
38+
state change events, are published on to the events bus.</para>
39+
<formalpara>
40+
<title>Use Cases</title>
41+
<para>The following are some of the use cases:</para>
42+
</formalpara>
43+
<itemizedlist>
44+
<listitem>
45+
<para>Usage or Billing Engines: A third-party cloud usage solution can implement a plug-in
46+
that can connects to &PRODUCT; to subscribe to &PRODUCT; events and generate usage data. The
47+
usage data is consumed by their usage software.</para>
48+
</listitem>
49+
<listitem>
50+
<para>AMQP plug-in can place all the events on the a message queue, then a AMQP message broker
51+
can provide topic-based notification to the subscribers.</para>
52+
</listitem>
53+
<listitem>
54+
<para>Publish and Subscribe notification service can be implemented as a pluggable service in
55+
&PRODUCT; that can provide rich set of APIs for event notification, such as topics-based
56+
subscription and notification. Additionally, the pluggable service can deal with
57+
multi-tenancy, authentication, and authorization issues.</para>
58+
</listitem>
59+
</itemizedlist>
60+
<formalpara>
61+
<title>Configuration</title>
62+
<para>As a &PRODUCT; administrator, perform the following one-time configuration to enable event
63+
notification framework. At run time no changes can control the behaviour.</para>
64+
</formalpara>
65+
<orderedlist>
66+
<listitem>
67+
<para>Open <filename>'componentContext.xml</filename>.</para>
68+
</listitem>
69+
<listitem>
70+
<para>Define a bean named <filename>eventNotificationBus</filename> as follows:</para>
71+
<itemizedlist>
72+
<listitem>
73+
<para>name : Specify a name for the bean.</para>
74+
</listitem>
75+
<listitem>
76+
<para>server : The name or the IP address of the RabbitMQ AMQP server.</para>
77+
</listitem>
78+
<listitem>
79+
<para>port : The port on which RabbitMQ server is running.</para>
80+
</listitem>
81+
<listitem>
82+
<para>username : The username associated with the account to access the RabbitMQ
83+
server.</para>
84+
</listitem>
85+
<listitem>
86+
<para>password : The password associated with the username of the account to access the
87+
RabbitMQ server.</para>
88+
</listitem>
89+
<listitem>
90+
<para>exchange : The exchange name on the RabbitMQ server where &PRODUCT; events are
91+
published.</para>
92+
<para>A sample bean is given below:</para>
93+
<programlisting>&lt;bean id="eventNotificationBus" class="org.apache.cloudstack.mom.rabbitmq.RabbitMQEventBus"&gt;
94+
&lt;property name="name" value="eventNotificationBus"/&gt;
95+
&lt;property name="server" value="127.0.0.1"/&gt;
96+
&lt;property name="port" value="5672"/&gt;
97+
&lt;property name="username" value="guest"/&gt;
98+
&lt;property name="password" value="guest"/&gt;
99+
&lt;property name="exchange" value="cloudstack-events"/&gt;
100+
&lt;/bean&gt;</programlisting>
101+
<para>The <filename>eventNotificationBus</filename> bean represents the
102+
<filename>org.apache.cloudstack.mom.rabbitmq.RabbitMQEventBus</filename> class.</para>
103+
</listitem>
104+
</itemizedlist>
105+
</listitem>
106+
<listitem>
107+
<para>Restart the Management Server.</para>
108+
</listitem>
109+
</orderedlist>
110+
</section>

‎docs/en-US/events.xml‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,17 @@
2121
specific language governing permissions and limitations
2222
under the License.
2323
-->
24-
2524
<section id="events">
26-
<title>Events</title>
27-
<xi:include href="events-log.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
28-
<xi:include href="standard-events.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
29-
<xi:include href="long-running-job-events.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
30-
<xi:include href="event-log-queries.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
25+
<title>Events</title>
26+
<para>An event is essentially a significant or meaningful change in the state of both virtual and
27+
physical resources associated with a cloud environment. Events are used by monitoring systems,
28+
usage and billing systems, or any other event-driven workflow systems to discern a pattern and
29+
make the right business decision. In &PRODUCT; an event could be a state change of virtual or
30+
psychical resources, an action performed by an user (action events), or policy based events
31+
(alerts).</para>
32+
<xi:include href="events-log.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
33+
<xi:include href="event-framework.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
34+
<xi:include href="standard-events.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
35+
<xi:include href="long-running-job-events.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
36+
<xi:include href="event-log-queries.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
3137
</section>

0 commit comments

Comments
 (0)