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 ESXi hosts 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 ESXi hosts – 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 ESXi host or powering off a virtual machine removes Event objects from local memory.

A standalone ESXi host 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 Web Services API allows you to create custom Event objects that convey information specific to your application. There are two types of custom events, the user log event and the extended event.

Creating User Log Events

The EventManager.LogUserEvent method allows you to create user log Event objects. You can associate your custom Event with any managed entity. User log events are useful for marking actions or status associated with the objects your application deals with.

To define a user log 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.

For example, suppose you have a reference to a virtual machine (myVMRef) and you want to log a message to record the fact that a virus check completed. You want to use myVMRef as a parameter to the LogUserEvent method in the next step.

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.

LogUserEvent(eMgrRef, myVMRef, "Completed virus check at 1:05 AM on Sunday December 21.");

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.

Creating Extended Events

The EventManager.EventEx method allows you to create an event that contains an arbitrary dictionary of key-value pairs. This kind of custom event allows greater flexibility to store application data that is not associated with a managed entity, and is not limited to a single string value. The custom event structure also contains more sophisticated metadata than user log events.

The following steps show pseudocode examples of the operations you need to do in your client code.

To define an extended Event

1	Obtain the managed object reference to the EventManager.

si = connection.retrieveServiceContent(svc_ref);

em = si.eventManager;

2	Choose a severity for the custom event.

severity = EventEventSeverity.warning;

3	Create a local copy of an extended event with metadata.

e = vim.event.EventEx(severity,

                      eventTypeId=”com.example.events.Total_System_Backup”,

                      createdTime = si.CurrentTime(),

                      chainId=0,

                      key=0,

                      userName=local_account_name);

4	Create a set of key-value pairs to store the information you want to associate with the event.

arg_list = {};

arg1 = vmodl.KeyAnyValue(key=”reason”, value=”Upcoming governance audit”);

arg2 = vmodl.KeyAnyValue(key=”datacenter”, value=”Washington South”);

arg3 = vmodl.KeyAnyValue(key=”organization”, value=”IT Cloud Services”);

arg_list.append(arg1, arg2, arg3);

5	Add the set of key-value pairs to the event object.

e.arguments = arg_list;

6	Use the Event Manager to post the event to the server.

em.PostEvent(e);