25.4. Methods

25.4.1. Searching Events

The events collection provides search queries similar to other resource collections. An additional feature when searching the events collection is the ability to search from a certain event. This queries all of events since a specified event.
Querying from an event requires an additional from parameter added before the search query. This from argument references an event id code.

Example 25.3. Searching from an event

GET /ovirt-engine/api/events;from=1012?search=type%3D30 HTTP/1.1
Accept: application/xml
This displays all events with type set to 30 since id="1012" 
HTTP/1.1 200 OK
Content-Type: application/xml
<events>
    <event id="1018" href="/ovirt-engine/api/events/1018">
        <description>User admin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-07-11T14:03:22.485+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/ovirt-engine/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    <event id="1016" href="/ovirt-engine/api/events/1016">
        <description>User admin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-07-11T14:03:07.236+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/ovirt-engine/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    <event id="1014" href="/ovirt-engine/api/events/1014">
        <description>User admin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-07-11T14:02:16.009+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/ovirt-engine/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
</events>

Example 25.4. Searching using a specific event severity

GET /ovirt-engine/api/events?search=severity>normal HTTP/1.1
Accept: application/xml
This displays all events with severity higher than normal. Severity levels include normal, warning, error and alert. 
HTTP/1.1 200 OK
Content-Type: application/xml
<events>
    <event id="2823" href="/ovirt-engine/api/events/2823">
        <description>Host Host-05 has time-drift of 36002 seconds while maximum configured value is 300 seconds.</description>
        <code>604</code>
        <severity>warning</severity>
        <time>2015-07-11T14:03:22.485+10:00</time>
        <host href= "/ovirt-engine/api/hosts/44e52bb2-27d6-4d35-8038-0c4b4db89789" id="44e52bb2-27d6-4d35-8038-0c4b4db89789"/>
        <cluster href= "/ovirt-engine/api/clusters/00000001-0001-0001-0001-00000000021b" id="00000001-0001-0001-0001-00000000021b"/>
        <origin>oVirt</origin>
        <custom_id>-1</custom_id>
        <flood_rate>30</flood_rate>
    </event>
...
</events>

25.4.2. Paginating Events

A virtualization environment generates a large amount of events after a period of time. However, the API only displays a default number of events for one search query. To display more than the default, the API separates results into pages with the page command in a search query.
The following search query tells the API to paginate results using a page value in combination with the sortby clause:
sortby time asc page 1
The sortby clause defines the base element to order of the results and whether the results are ascending or descending. For search queries of events, set the base element to time and the order to ascending (asc) so the API displays all events from the creation of your virtualization environment.
The page condition defines the page number. One page equals the default number of events to list. Pagination begins at page 1. To view more pages, increase the page value:
sortby time asc page 2
sortby time asc page 3
sortby time asc page 4

Example 25.5. Paginating events

This example paginates event resources. The URL-encoded request is: 
GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%201 HTTP/1.1
Accept: application/xml
Increase the page value to view the next page of results. 
GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%202 HTTP/1.1
Accept: application/xml
Use an additional from argument to set the starting id. 
GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%202&from=30 HTTP/1.1
Accept: application/xml

25.4.3. Adding Events

The API can add custom events with a POST request to the events collection. A new event requires the description, severity, origin, and custom_id elements. Custom events can also include flood_rate, user id, and the id codes of any resources relevant to the event. host and storage_domain elements can contain the external_status element to set an external health status.

Example 25.6. Adding a custom event to the event list

POST /ovirt-engine/api/events HTTP/1.1
Accept: application/xml
Content-type: application/xml

<event>
  <description>The heat of the host is above 30 Oc</description>
  <severity>warning</severity>
  <origin>HP Openview</origin>
  <custom_id>1</custom_id>
  <flood_rate>30</flood_rate>
  <host id="f59a29cd-587d-48a3-b72a-db537eb21957" >
    <external_status>
       <state>warning</state>
    </external_status>
  </host>
</event>

25.4.4. Removing Events

Removal of an event from the event list requires a DELETE request.

Example 25.7. Removing an event

DELETE /ovirt-engine/api/events/1705 HTTP/1.1

HTTP/1.1 204 No Content