Using an EventHistoryCollector

An EventHistoryCollector lets you gather information about events that the server has generated. You create an EventHistoryCollector using the EventManager.CreateCollectorForEvents method.

To create an EventHistoryCollector

1	Identify the type of Event objects that you want to collect, and create an instance of an EventFilterSpec data object that specifies your filter criteria. See Creating an EventHistoryCollector Filter.

The EventFilterSpec includes an eventTypeId property, which you use to limit the set of collected event objects to specific types. You can also provide a time range in the EventFilterSpec, by defining an EventFilterSpecByTime data object for its time property. See the vSphere API Reference for details.

2	Obtain the managed object reference to the EventManager on your server instance.

3	Submit the filter and the reference to the server in the CreateEventHistoryCollector operation. The server returns a reference to an EventHistoryCollector object.

After you have created the HistoryCollector, the server appends new objects that meet the filter criteria to the collection as they occur. The system appends the new object to the collection by placing it in the first position of the latestPage and it removes the oldest object from the collection. The latestPage property of the EventHistoryCollector object has a property that consists of the 1000 most recent objects in the collection. Use a PropertyCollector to obtain the items from the latestPage property.

A HistoryCollector exists only for the duration of the session that instantiated it. You invoke the DestroyCollector operation to explicitly eliminate the collector before the session ends.

Creating an EventHistoryCollector Filter

When you create an EventHistoryCollector, you can define filters. For example, rather than returning all Event objects associated with virtual machines, you might create a filter to collect only those Event objects associated with virtual machines that were executed by the backup-administrator between 2:00 and 4:00 a.m. on a specific date.

The EventFilterSpec object allows you to specify the collection criteria. Most of the properties are optional and can be submitted as null values. The EventFilterSpec lets you collect events based on user name, entity type, time, and state of the Event.

Managing the HistoryCollector

The HistoryCollector managed object provides operations for managing the life-cycle and scrollable view of a collection.

■	DestroyCollector – A HistoryCollector exists only for the current session. Invoke the DestroyCollector operation to explicitly destroy the collector before the session ends.

■	ResetCollector – Adjusts the starting position for the subset of objects from the collector to the object immediately preceding the current latestPage.

■	RewindCollector – Positions the latestPage to the oldest item in the array. When a HistoryCollector is created, this is the default location.

■

SetCollectorPageSize – Accepts an integer parameter to set the size of the latestPage property of a HistoryCollector. The default size of a HistoryCollector is an array that consists of at most 1000 objects of the appropriate type (Task, Event). The array is sorted by creation date and time of the objects.