Updated Branches: refs/heads/master 9c6ced96c -> a508309e7
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/master Commit: a508309e7d87d1ab213b5f507ab5660169c202af Parents: 9c6ced9 Author: Radhika PC <[email protected]> Authored: Wed Feb 27 18:00:31 2013 +0530 Committer: Radhika PC <[email protected]> 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>
