docs/en-US/event-framework.xml

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