Managed Object - PerformanceManager

Property of: ServiceContent
See also: PerfCompositeMetric, PerfCounterInfo, PerfEntityMetricBase, PerfInterval, PerfMetricId, PerformanceDescription, PerfProviderSummary, PerfQuerySpec

Managed Object Description

The PerformanceManager object provides the interface for querying performance statistics.

The PerformanceManager object manages performance statistics collected from various components, such as a host, virtual machine, clusters and resource pools. The collection of performance statistics is associated with but not limited to managed entities defined for the object model. Those managed entities that are capable of returning performance statistics are Performance Providers. The capabilities of performance providers can be retrieved using (QueryPerfProviderSummary). In PerformanceManager, three sets of methods are used to perform the following:

Query or update intervals for historical statistics.
Query performance statistics.
Query metadata information about performance statistics counters.

Query operations for statistics are (QueryPerf) and (QueryPerfComposite). QueryPerf supports queries on multiple entities by allowing an array for the entity parameter. To query for a single entity, pass one entity into the array. QueryPerfComposite supports querying composite statistics for one entity at a time and provides the statistics for the queried metrics for the entity and its holding entities. For example, a Host and its holding entities which are child virtual machines.

Performance Counters and Performance Metrics

A performance counter is a unit of information that can be collected about a managed entity. A performance counter is identified by a CounterID. Performance counters can also be represented using a dotted string notation, which includes the counter's group, name, and roll-up type. For example: cpu.usage.min indicates the minimum CPU usage in a collected sample.

A performance metric represents the actual information collected. For the entities in question such as a host or virtual machine, there might be multiple instances of the device for which the same performance counter can be collected. Each instance is a performance metric. For example, Usage is a performance counter for CPU utilization, while Usage collected for CPU #1 for a host is a performance metric, which is represented as counter cpu usage with device instance 1. A performance metric is identified by a MetricId. The MetricId consists of two parts:

CounterId: The integer that identifies the performance counter.
InstanceId: The name of the instance such as CPU "0" or disk "A".

Performance counters are organized by counter groups. The supported counter groups are cpu, memory, network, disk, system, rescpu and drs. There are a number of counters under each group. Some of the counters are sampled for each instance of the object such as the virtual machine CPU system counter. Other values collected for all instances of the object such as the host CPU usage counter.

Performance Counter Categories

Each performance counter contains information in the following categories:

unit: The statistic's units. Some examples of possible types of units include percent, millisecond, or KB.
description: A textual description of the performance counter, potentially including information about what value it reports.
type of statistic: Describes the nature of the statistical value that is collected or calculated for this counter. Statistics may indicate an amount of change, an absolute value, or a rate value.
rollup type: Identifies the type of statistic rolled up during the performance interval. The value may be no value, an average, a minimum, a maximum, a summation of all of the statistics, or the latest statistic.
level: The minimum statistics collection level at which this performance counter will be collected by VirtualCenter.

Performance Counter Values

The performance counters and categories for each counter data object type are listed in the tables associated with the following links:

Properties

Name	Type	Description
description P	PerformanceDescription	The static description strings.
historicalInterval* P	PerfInterval[]	Retrieves all configured historical archive sampling intervals. Refer to HistoricalInterval for a description of historical intervals.
perfCounter* P	PerfCounterInfo[]	Retrieves counter information for all supported performance counters in the system.

*May not be presentP Required privilege: System.View

Methods

Methods defined in this Managed Object
CreatePerfInterval, QueryAvailablePerfMetric, QueryPerf, QueryPerfComposite, QueryPerfCounter, QueryPerfCounterByLevel, QueryPerfProviderSummary, RemovePerfInterval, UpdatePerfInterval

CreatePerfInterval

Deprecated. As of VI API 2.5, use UpdatePerfInterval. Historical intervals cannot be created.

Adds a new archive interval. The new interval must meet the following conditions:

The new sampling period must be a multiple of a previous one.
The new sampling length must be longer than a previous one.
The user-specified name of the historical interval must be unique.

The following example is valid:

period = 300, length = 7 days
period = 600, length = 8 days

The following example is invalid because the second period is not a multiple of the first one:

period = 300, length = 7 days
period = 500, length = 8 days

The following example is invalid because the second length is shorter than the first one:

period = 300, length = 7 days
period = 600, length = 6 days

Required Privileges: Performance.ModifyIntervals

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the PerformanceManager used to make the method call.

intervalId

PerfInterval

The interval being created. This consists of the following:

The number of seconds the information is kept in the database.
The user-specified name of the historical interval.
The sampling period for statistics archiving in seconds.

Return Value

Type	Description
None

Faults

Type	Description
InvalidArgument	Thrown if the set of arguments passed to the function is not specified correctly.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreatePerfInterval" type="vim25:CreatePerfIntervalRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreatePerfIntervalResponse">
            <complexType/>
         </element>

QueryAvailablePerfMetric

Retrieves available performance metrics for the specified ManagedObject between the optional beginTime and endTime. These are the performance statistics that are available for the given time interval.

Required Privileges: System.Read

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the PerformanceManager used to make the method call.
entity	ManagedObjectReference	The ManagedObject for which available performance metrics are queried.
beginTime*	xsd:dateTime	The time from which available performance metrics are gathered. Corresponds to server time. When the beginTime is omitted, the returned metrics start from the first available metric in the system.
endTime*	xsd:dateTime	The time up to which available performance metrics are gathered. Corresponds to server time. When the endTime is omitted, the returned result includes up to the most recent metric value.
intervalId*	xsd:int	Specify a particular interval that the query is interested in. Acceptable intervals are the refreshRate returned in QueryProviderSummary, which is used to retrieve available metrics for real-time performance statistics, or one of the historical intervals, which are used to retrieve available metrics for historical performance statistics. If interval is not specified, system returns available metrics for historical statistics.

*Need not be set

Return Value

Type	Description
PerfMetricId[]	An array of performance metrics with a performance counter ID and an instance name.

Faults

Type	Description
InvalidArgument	Thrown if the set of arguments passed to the function is not specified correctly.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryAvailablePerfMetric" type="vim25:QueryAvailablePerfMetricRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryAvailablePerfMetricResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:PerfMetricId" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

QueryPerf

Returns performance statistics for the entity. The client can limit the returned information by specifying a list of metrics and a suggested sample interval ID. Server accepts either the refreshRate or one of the historical intervals as input interval.

Required Privileges: System.View

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the PerformanceManager used to make the method call.

querySpec

PerfQuerySpec[]

List of QuerySpec objects. Each QuerySpec object specifies a ManagedObject for which statistics are to be retrieved and the relevant query parameters.

When the optional interval in querySpec is omitted, the information is returned in its original sample interval. If the range between startTime and endTime crosses multiple sample interval periods, the result contains data reported on the largest interval in the period. If an interval is specified, then the server tries to summarize the information for the suggested interval. If that is not possible, then the server summarizes the returned information in a best interval available.

Raw data feed workaround: Normally, QueryPerf will return performance statistics stored in the VirtualCenter database. However this may not be suitable for certain applications. For example, applications that treat VirtualCenter as a raw data source, query for performance statistics regularly (say every 5 minutes) and extract the data for external archival and reporting. Such applications need better query performance. These applications should query statistics using QueryPerf for the base historical interval (5 minutes by default) having a start and end time range within 30 minutes from the current VirtualCenter server system time. These QueryPerf calls will have better performance than other QueryPerf calls.

Return Value

Type	Description
PerfEntityMetricBase[]	The metric values for the specified entity or entities.

Faults

Type	Description
InvalidArgument	Thrown if the set of arguments passed to the function is not specified correctly.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryPerf" type="vim25:QueryPerfRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryPerfResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:PerfEntityMetricBase" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

QueryPerfComposite

Returns performance statistics for the entity and the breakdown for its child entities in the form of CompositeEntityMetric. The client can limit the returned information by specifying a list of metrics, and a suggested sample interval ID. The server accepts either the refreshRate or one of the historical intervals as the input interval. For example, this function can be used to retrieve statistics for a host and all its registered virtual machines for the given time period. This function only does one level breakdown. For a resource pool, it only breaks down to its direct child resource pools and virtual machines.

Required Privileges: System.View

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the PerformanceManager used to make the method call.

querySpec

PerfQuerySpec

The PerfQuerySpec object specifying the query parameters.

When the optional interval is omitted, the information is returned in its original sample interval. If the range between startTime and endTime crosses multiple sample interval periods, the result contains data reported on the largest interval in the period. If an interval is specified, then the server tries to summarize the information for the suggested interval. If that is not possible, then the server summarizes the returned information in a best interval available. The performance metrics always are returned in a single interval.

The metrics specified in the metricId property of QuerySpec must be available in common for both the aggregated entity and child entities. Any input metric ID that are not in common is ignored. Most metric IDs with non-empty instance IDs are not likely to be in common. The metricId property can not be empty for querying composite statistics.

Return Value

Type	Description
PerfCompositeMetric	The metric values for the specified entity and its holding entities.

Faults

Type	Description
InvalidArgument	Thrown if the set of arguments passed to the function is not specified correctly.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryPerfComposite" type="vim25:QueryPerfCompositeRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryPerfCompositeResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:PerfCompositeMetric"/>
               </sequence>
            </complexType>
         </element>

QueryPerfCounter

Retrieves counter information for the list of counter IDs passed in.

Required Privileges: System.View

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the PerformanceManager used to make the method call.
counterId	xsd:int[]	An array of one or more counterIds representing performance counters for which information is being retrieved.

Return Value

Type	Description
PerfCounterInfo[]	An array consisting of performance counter information for the specified counterIds.

Faults

Type	Description
InvalidArgument	Thrown if the set of arguments passed to the function is not specified correctly.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryPerfCounter" type="vim25:QueryPerfCounterRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryPerfCounterResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:PerfCounterInfo" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

QueryPerfCounterByLevel

Rerieve the set of counters that are available at a statistics collection level. The statistics collection level determines which metrics are stored in VirtualCenter and this can be configured for every historical interval. The value can be set between 1 and 4, with 4 being the maximum amount of data. Each higher number setting increases the amount of data being colelcted. The type of information collected at each level is:

Level 1: Includes basic metrics: Average Usage for CPU, Memory, Disk, and Network; System Uptime, System Heartbeat, and DRS metrics. Does not include statistics for devices.
Level 2: Includes all metrics for CPU, Memory, Disk, and Network counters (average, summation, and latest rollup types; does not include maximum and minimum rollup types); System Uptime, System Heartbeat, and DRS metrics. Does not include statistics for devices.
Level 3: Includes all metrics (including device metrics) for all counter groups (average, summation, and latest rollup types; does not include maximum and minimum rollup types).
Level 4: Includes all metrics supported by VirtualCenter, including maximum and minimum rollup types.

Required Privileges: System.View
Since: VI API 2.5

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the PerformanceManager used to make the method call.
level	xsd:int	The statistics collection level for which the set of counters is being queried. This can be a value between 1 and 4.

Return Value

Type	Description
PerfCounterInfo[]

Faults

Type	Description
InvalidArgument	Thrown if an invalid level is specified.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryPerfCounterByLevel" type="vim25:QueryPerfCounterByLevelRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryPerfCounterByLevelResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:PerfCounterInfo" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

QueryPerfProviderSummary

Returns a ProviderSummary object for a ManagedObject for which performance statistics can be queried. Also indicates whether current or summary statistics are supported. If the input managed entity is not a performance provider, an InvalidArgument exception is thrown.

Required Privileges: System.Read

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the PerformanceManager used to make the method call.
entity	ManagedObjectReference

Return Value

Type	Description
PerfProviderSummary

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryPerfProviderSummary" type="vim25:QueryPerfProviderSummaryRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryPerfProviderSummaryResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:PerfProviderSummary"/>
               </sequence>
            </complexType>
         </element>

RemovePerfInterval

Deprecated. As of VI API 2.5, use UpdatePerfInterval. Historical intervals cannot be removed.

Removes an interval from the list.

Required Privileges: Performance.ModifyIntervals

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the PerformanceManager used to make the method call.
samplePeriod	xsd:int	The sampling period in seconds for the particular interval being removed.

Return Value

Type	Description
None

Faults

Type	Description
InvalidArgument	Thrown if the set of arguments passed to the function is not specified correctly.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemovePerfInterval" type="vim25:RemovePerfIntervalRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemovePerfIntervalResponse">
            <complexType/>
         </element>

UpdatePerfInterval

Updates the configuration of a historical interval. VirtualCenter ships with a fixed set of historical intervals HistoricalInterval. However they can be modified in the following ways:

The sampling period of the "Past Day" interval can be reduced from 5 minutes to 1, 2 or 3 minutes.
The length of the "Past Day" interval can be increased from 1 day up to 3 days.
The length of the "Past Year" interval can be increased from 1 year up to 3 years.
The statistics level of an interval can be changed. However the level of a smaller historical interval can not be less than the level of a larger historical interval.
An interval can be enabled or disabled. Note that when an interval is disabled, all the higher intervals will also be disabled.

Required Privileges: Performance.ModifyIntervals

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the PerformanceManager used to make the method call.

interval

PerfInterval

The historical interval being updated. This consists of the following:

The number of seconds the information is kept in the database.
The user-specified name of the historical interval.
The sampling period for statistics archiving in seconds.
The statistics collection level for the interval.
Boolean to indicate if the interval is enabled.

Return Value

Type	Description
None

Faults

Type	Description
InvalidArgument	Thrown if the set of arguments passed to the function is not specified correctly or if the update does not conform to the rules mentioned above.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdatePerfInterval" type="vim25:UpdatePerfIntervalRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdatePerfIntervalResponse">
            <complexType/>
         </element>