Previous page

Next page

Locate page in Contents

Print this page

Events and Alerts

Event reporters are operators that monitor the system for critical system events, such as a server status change or server configuration change. They also allow to subscribe to and receive automatic notifications if an alert is raised on a server due to resource allocation problems. These operators are subscription-based, meaning that the client must subscribe to the event notification services in order to receive notifications. The following types of subscriptions are currently available:

Subscription Name

Description

env_status_subscription

Triggers when the status of a server changes, including state and transition changes. The event reports the status change for every server that Agent is aware of. If you subscribe for the event on the Master Node in a Virtuozzo group, you will receive the notifications about the status changes of every server in the entire group.

env_config_subscription

Triggers when the configuration of a server changes. If subscribed on a Master Node in a group, reports the changes across the entire group hierarchy.

alerts_subscription

Reports resource allocation problems such as approaching or breaking certain limits.

To subscribe to an event notification, make the following call:

<packet version="4.0.0" id="2">

  <data>

    <system>

      <subscribe>

        <name>subscription_name</name>

      </subscribe>

    </system>

  </data>

</packet>

Where subscription_name is the name of one of the event subscriptions from the table above. As soon as the event takes place (or an alert is raised), a message will be sent to your client program containing the event data. You recognize the event notification message by examining the value of the target element in the message header, which should contain the name of the subscription, i.e. the same name that you passed to the call when you subscribed to the event. Please remember that any message may have more than one target element; when searching for a particular target, make sure to look through all of them.

The following examples illustrates a notification message received when one of the servers was manually stopped. The message contains the ID of the server that generated the event, the text message that may be presented to the user, and the event data (old/new state and transition codes). Note that one of the target elements contains the same value as the one we used in the name element in the request, which is env_status_subscription. Please also note that the inner data structure contains the elements specific to this event type -- in this particular case, the env_status_event element.

Input

Subscribing to the status change events.

<packet version="4.0.0" id="2">

  <data>

    <system>

      <subscribe>

        <name>env_status_subscription</name>

      </subscribe>

    </system>

  </data>

</packet>

Output

A notification that was received after a server was shut down.

<packet version="4.0.0">

  <target>events_subscription</target>

  <target>env_status_subscription</target>

  <data>

    <event>

      <eid>849c9be9-5fbb-4e7d-b100-f841f86c150e</eid>

      <time>1155317636</time>

      <source></source>

      <category>env_status_subscription</category>

      <sid>XXX</sid>

      <data>

        <env_status_event>

          <eid>62ec514e-bc38-4aee-830d-cc802ee2aadd</eid>

          <new>

            <state>3</state>

          </new>

          <old>

            <state>3</state>

            <transition>5</transition>

          </old>

        </env_status_event>

      </data>

      <info>

        <message>

           RW52aXJvbm1lbnQgJWVpZCUgc3RhdHVzIGNoYW5nZWQgZnJvbSAlb2xkJSB0byAlbmV3JQ==

        </message>

        <name></name>

        <translate/>

        <parameter>

          <message>NjJlYzUxNGUtYmMzOC00YWVlLTgzMGQtY2M4MDJlZTJhYWRk</message>

          <name>eid</name>

        </parameter>

        <parameter>

          <message>Mw==</message>

          <name>new</name>

          <translate/>

        </parameter>

        <parameter>

          <message>Mw==</message>

          <name>old</name>

          <translate/>

        </parameter>

      </info>

    </event>

  </data>

</packet>

A subscription remains in effect for the duration of the session. If a client program disconnects and then re-connects again, the subscription is canceled and the client has to subscribe again. The events that might have happened during that time will be unknown to this client. However, the majority of the events are logged internally by Agent. The even log can be accessed using the event_log interface.

To stop receiving the event notifications, use the following call:

Input

<packet version="4.0.0" id="2">

  <data>

    <system>

      <unsubscribe>

        <name>subscription_name</name>

      </unsubscribe>

    </system>

  </data>

</packet>

Please send us your feedback on this help page