Summary:
Subscribes to system event notifications.
Request specification:
Name |
Min/Max |
Type |
Description |
|
|
|
|
|
|
|
|
|
|
|
Subscription name. See Events/Elements for the available subscriptions. |
|
|
|
|
Returns:
Name |
Min/Max |
Type |
Description |
|
|
Event data. |
Description:
Subscription is a mechanism allowing to monitor the system for critical events, such as the server status changes, Server configuration changes, and some others. It also allows to receive automatic notifications if an alert is raised on the server due to resource allocation problems. To subscribe to the event or an alert notification service, execute this call passing the subscription name.
As soon as the event takes place (or an alert is raised), a message is sent to your client program containing the event data. You recognize the message by examining the value of the target
element in the message header, which should contain the same event subscription name as the one you used when you subscribed to the event notifications. Please remember that an Agent message may have more than one target
element. When searching for a particular value, always remember to look through all occurrences of the target
element.
A subscription remains in effect for the duration of the user session. If the client program disconnects and then re-connects again, the subscription is canceled and the client has to subscribe again. The events that triggered during that time (if any) will be unknown to this client. However, the majority of the events are logged internally by Agent, so you can retrieve this information later. The even log can be accessed using the event_log
interface.
For information on the available events and alerts, see the Events section.
To stop receiving the event notifications, use the unsubscribe
call.
Example:
Input
Subscribing to the environment status change events.
<packet version="4.0.0" id="2">
<data>
<system>
<subscribe>
<name>env_status_subscription</name>
</subscribe>
</system>
</data>
</packet>
Output
Subscription was a success.
<packet priority="0" version="4.0.0" id="2">
<origin>servd</origin>
<target>vzclient1</target>
<data>
<system>
<ok/>
</system>
</data>
</packet>
Output
The following is a notification message received when one of the Environments was stopped. The message contains the Server ID that generated the event, the text message describing the event, and the event data (the old and the new server 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
-- that's how you recognize the message. Please also note that the inner data
structure contains the elements specific to this event type, which in this particular case is the env_status_event
element.
<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>
<src>
<director>gend</director>
</src>
</packet>