class OvirtSDK4::EventsService

Public Class Methods

new(connection, path) click to toggle source

Creates a new implementation of the service.

@param connection [Connection] The connection to be used by this service.

@param path [String] The relative path of this service, for example `vms/123/disks`.

@api private

# File lib/ovirtsdk4/services.rb, line 7717
def initialize(connection, path)
  @connection = connection
  @path = path
end

Public Instance Methods

add(event, opts = {}) click to toggle source

Adds an external event to the internal audit log.

This is intended for integration with external systems that detect or produce events relevant for the administrator of the system. For example, an external monitoring tool may be able to detect that a file system is full inside the guest operating system of a virtual machine. This event can be added to the internal audit log sending a request like this:

source

POST /ovirt-engine/api/events <event>

<description>File system /home is full</description>
<severity>alert</severity>
<origin>mymonitor</origin>
<custom_id>1467879754</custom_id>

</event>


Events can also be linked to specific objects. For example, the above event could be linked to the specific virtual machine where it happened, using the `vm` link:

source

POST /ovirt-engine/api/events <event>

<description>File system /home is full</description>
<severity>alert</severity>
<origin>mymonitor</origin>
<custom_id>1467879754</custom_id>
<vm id="aae98225-5b73-490d-a252-899209af17e9"/>

</event>


NOTE: When using links, like the `vm` in the previous example, only the `id` attribute is accepted. The `name` attribute, if provided, is simply ignored.

@param event [Event] The `event` to add.

@param opts [Hash] Additional options.

@return [Event]

# File lib/ovirtsdk4/services.rb, line 7765
def add(event, opts = {})
  if event.is_a?(Hash)
    event = OvirtSDK4::Event.new(event)
  end
  query = {}
  request = HttpRequest.new(method: :POST, url: @path, query: query)
  begin
    writer = XmlWriter.new(nil, true)
    EventWriter.write_one(event, writer)
    request.body = writer.string
  ensure
    writer.close
  end
  response = @connection.send(request)
  case response.code
  when 200, 201, 202
    begin
      reader = XmlReader.new(response.body)
      return EventReader.read_one(reader)
    ensure
      reader.close
    end
  else
    check_fault(response)
  end
end
event_service(id) click to toggle source

Reference to the service that manages a specific event.

@param id [String] The identifier of the `event`.

@return [EventService] A reference to the `event` service.

# File lib/ovirtsdk4/services.rb, line 7991
def event_service(id)
  EventService.new(@connection, "#{@path}/#{id}")
end
list(opts = {}) click to toggle source

Get list of events.

source

GET /ovirt-engine/api/events


To the above request we get following response:

source,xml

<events>

<event href="/ovirt-engine/api/events/2" id="2">
  <description>User admin@internal-authz logged out.</description>
  <code>31</code>
  <correlation_id>1e892ea9</correlation_id>
  <custom_id>-1</custom_id>
  <flood_rate>30</flood_rate>
  <origin>oVirt</origin>
  <severity>normal</severity>
  <time>2016-09-14T12:14:34.541+02:00</time>
  <user href="/ovirt-engine/api/users/57d91d48-00da-0137-0138-000000000244" id="57d91d48-00da-0137-0138-000000000244"/>
</event>
<event href="/ovirt-engine/api/events/1" id="1">
  <description>User admin logged in.</description>
  <code>30</code>
  <correlation_id>1fbd81f4</correlation_id>
  <custom_id>-1</custom_id>
  <flood_rate>30</flood_rate>
  <origin>oVirt</origin>
  <severity>normal</severity>
  <time>2016-09-14T11:54:35.229+02:00</time>
  <user href="/ovirt-engine/api/users/57d91d48-00da-0137-0138-000000000244" id="57d91d48-00da-0137-0138-000000000244"/>
</event>

</events>


The following events occur:

  • id=“1” - The API logs in the admin user account.

  • id=“2” - The API logs out of the admin user account.

@param opts [Hash] Additional options.

@option opts [Boolean] :case_sensitive Indicates if the search performed using the `search` parameter should be performed taking case into

account. The default value is `true`, which means that case is taken into account. If you want to search
ignoring case set it to `false`.

@option opts [Integer] :from Indicates the identifier of the the first event that should be returned. The identifiers of events are

strictly increasing, so when this parameter is used only the events with that identifiers equal or greater
than the given value will be returned. For example, the following request will return only the events
with identifiers greater or equal than `123`:

[source]
----
GET /ovirt-engine/api/events?from=123
----

This parameter is optional, and if not specified then the first event returned will be most recently
generated.

@option opts [Integer] :max Sets the maximum number of events to return. If not specified all the events are returned.

@option opts [String] :search The events service provides search queries similar to other resource services.

We can search by providing specific severity.

[source]
----
GET /ovirt-engine/api/events?search=severity%3Dnormal
----

To the above request we get a list of events which severity is equal to `normal`:

[source,xml]
----
<events>
  <event href="/ovirt-engine/api/events/2" id="2">
    <description>User admin@internal-authz logged out.</description>
    <code>31</code>
    <correlation_id>1fbd81f4</correlation_id>
    <custom_id>-1</custom_id>
    <flood_rate>30</flood_rate>
    <origin>oVirt</origin>
    <severity>normal</severity>
    <time>2016-09-14T11:54:35.229+02:00</time>
    <user href="/ovirt-engine/api/users/57d91d48-00da-0137-0138-000000000244" id="57d91d48-00da-0137-0138-000000000244"/>
  </event>
  <event href="/ovirt-engine/api/events/1" id="1">
    <description>Affinity Rules Enforcement Manager started.</description>
    <code>10780</code>
    <custom_id>-1</custom_id>
    <flood_rate>30</flood_rate>
    <origin>oVirt</origin>
    <severity>normal</severity>
    <time>2016-09-14T11:52:18.861+02:00</time>
  </event>
</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:

[source]
----
sortby time asc page 1
----

Below example paginates event resources. The URL-encoded request is:

[source]
----
GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%201
----

Increase the page value to view the next page of results.

[source]
----
GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%202
----

@return [Array<Event>]

# File lib/ovirtsdk4/services.rb, line 7921
def list(opts = {})
  query = {}
  value = opts[:case_sensitive]
  unless value.nil?
    value = Writer.render_boolean(value)
    query['case_sensitive'] = value
  end
  value = opts[:from]
  unless value.nil?
    value = Writer.render_integer(value)
    query['from'] = value
  end
  value = opts[:max]
  unless value.nil?
    value = Writer.render_integer(value)
    query['max'] = value
  end
  value = opts[:search]
  unless value.nil?
    query['search'] = value
  end
  request = HttpRequest.new(method: :GET, url: @path, query: query)
  response = @connection.send(request)
  case response.code
  when 200
    begin
      reader = XmlReader.new(response.body)
      return EventReader.read_many(reader)
    ensure
      reader.close
    end
  else
    check_fault(response)
  end
end
service(path) click to toggle source

Locates the service corresponding to the given path.

@param path [String] The path of the service.

@return [Service] A reference to the service.

# File lib/ovirtsdk4/services.rb, line 8002
def service(path)
  if path.nil? || path == ''
    return self
  end
  index = path.index('/')
  if index.nil?
    return event_service(path)
  end
  return event_service(path[0..(index - 1)]).service(path[(index +1)..-1])
end
to_s() click to toggle source

Returns an string representation of this service.

@return [String]

# File lib/ovirtsdk4/services.rb, line 8018
def to_s
  "#<#{EventsService}:#{@path}>"
end
undelete(opts = {}) click to toggle source

Executes the `undelete` method.

@param opts [Hash] Additional options.

@option opts [Boolean] :async Indicates if the un-delete should be performed asynchronously.

# File lib/ovirtsdk4/services.rb, line 7964
def undelete(opts = {})
  action = Action.new(opts)
  writer = XmlWriter.new(nil, true)
  ActionWriter.write_one(action, writer)
  body = writer.string
  writer.close
  request = HttpRequest.new(
    method: :POST,
    url: "#{@path}/undelete",
    body: body
  )
  response = @connection.send(request)
  case response.code
  when 200
    action = check_action(response)
  else
    check_action(response)
  end
end