Understanding Events

An Event is a data object type that contains information about state changes of managed entities and other objects on the server. Events include user actions and system actions that occur on datacenters, datastores, clusters, hosts, resource pools, virtual machines, networks, and distributed virtual switches. For example, these common system activities generate one or more Event data objects:

■	Powering a virtual machine on or off

■	Creating a virtual machine

■	Installing VMware Tools on the guest OS of a virtual machine

■	Reconfiguring a compute resource

■	Adding a newly configured ESX/ESXi system to a vCenter Server system

In the vSphere Client, information from Event objects generated on a standalone ESX/ESXi system displays in the Events tab. For managed hosts, information from Event objects displays in the Tasks & Events tab.

Persistence of Event objects depends on the system setup.

■	Standalone ESX/ESXi systems – Event objects are not persistent. Events are retained only for as long as the host system’s local memory can contain them. Rebooting a standalone ESX/ESXi host or powering off a virtual machine removes Event objects from local memory.

A standalone ESX/ESXi system might keep about 15 minutes worth of Event data, but this can vary depending on the processing load of the host, the number of virtual machines, and other factors.

■	Managed ESX/ESXi systems. Event objects are persistent. Managed ESX/ESXi systems send Event data to the vCenter Server system that manages them, and the vCenter Server system stores the information its database.

You can use the event sample applications included in the SDK package with either managed or standalone ESX/ESXi systems and with vCenter Server systems.

Using an EventHistoryCollector, you can obtain information about these objects as they are being collected on a specific ESX/ESXi system, or from a specific historical period from the database. See Using an EventHistoryCollector.

Managing Events with EventManager

EventManager is the service interface for working with the event infrastructure. EventManager Managed Object and Associated Objects shows EventManager and related objects. An EventManager has these properties:

■	A description property, defined as an instance of an EventDescription data object, which contains an event category and other information.

■	A latestEvent property that contains the most recent Event data object in memory.

■	A maxCollector property that specifies the number of EventHistoryCollector objects per client session that can be created. This value is set by the vCenter Server system.

EventManager Managed Object and Associated Objects

Event Data Objects

Event subtypes define the events that the system generates. Event Data Object and Sample Subtypes shows only a few of the subtypes that extend the Event data object. For example, TaskEvent inherits all Event properties and includes an info property that is an instance of a TaskInfo object (see Monitoring TaskInfo Properties).

The following event objects are commonly generated by a console-style client application:

com.vmware.vim.VmPoweredOnEvent

com.vmware.vim.VmStartingEvent

com.vmware.vim.VmReconfiguredEvent

com.vmware.vim.VmCreatedEvent

com.vmware.vim.VmBeingCreatedEvent

Event Data Object and Sample Subtypes

Formatting Event Message Content

When displayed at the console, Event data objects are not formatted and do not provide context information. You can format an Event message using the predefined string in the Event.fullFormattedMessage property.

You can also format an Event message based on contextual information. At runtime, the Event data object is populated with values that contain information associated with the source of an event, for example, the Event data object’s computeResource, datacenter, ds, dvs, host, net, and vm properties.

You can use the properties of an Event object with the information in the EventDescriptionEventDetail in EventManager.description.eventInfo to format event messages.

Creating Custom Events

The EventManager. LogUserEvent method allows you to create custom Event objects. You can associate your custom Event with any managed entity.

To define a custom Event

1	Obtain the managed object reference to the EventManager.

..

ManagedObjectReference _svcRef = new ManagedObjectReference();

ServiceContent _sic = my_conn.retrieveServiceContent(_svcRef);

ManagedObjectReference eMgrRef = _sic.getEventManager();

...

2	Obtain the managed object reference to the entity with which you are associating the Event.

3	Call the LogUserEvent method, passing in the EventManager and the Event reference and a string consisting of the Event message for the msg parameter of the operation.

User-defined Event objects display in the vSphere Client among the other events on the system, with the prefix User logged event: followed by the text submitted in your msg parameter. In other client applications, such as in the console-based Event sample applications, custom events display as com.vmware.vim.GeneralUserEvent objects.