Managed Object - PerformanceManager

Property of: ServiceContent
See also: ManagedEntity, 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:

Create, remove, 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.
entity: Entities from which the performance counter is collected. This can include virtual machines, hosts, clusters, or resource pools.

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. Historical intervals are identified by an interval ID. An interval ID indicates the number of seconds for which the performance statistics are summarized. For example, for an interval that summarizes statistics for five minute intervals, the interval ID is 300 (60x5). Apart from the interval ID, each configured interval has a string description that the user provides to "name" the configuration. The user can choose any sentence to describe the sampling interval. The description does not effect system behavior.
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, QueryPerfProviderSummary, RemovePerfInterval, UpdatePerfInterval

CreatePerfInterval

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" name="CreatePerfInterval">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="intervalId" type="vim2:PerfInterval"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="CreatePerfIntervalResponse">
            <complexType/>
         </element>

QueryAvailablePerfMetric

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

Required Privileges: None

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the PerformanceManager used to make the method call.
entity P	ManagedObjectReference to a ManagedEntity	The ManagedEntity 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 P Required privilege: System.Read

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" name="QueryAvailablePerfMetric">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="entity" type="vim2:ManagedObjectReference"/>
                  <element name="beginTime" type="xsd:dateTime" minOccurs="0"/>
                  <element name="endTime" type="xsd:dateTime" minOccurs="0"/>
                  <element name="intervalId" type="xsd:int" minOccurs="0"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="QueryAvailablePerfMetricResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2: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 ManagedEntity 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. The performance metrics always are returned in a single interval.

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" name="QueryPerf">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="querySpec" type="vim2:PerfQuerySpec" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="QueryPerfResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2: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 QuerySpec 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" name="QueryPerfComposite">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="querySpec" type="vim2:PerfQuerySpec"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="QueryPerfCompositeResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2: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" name="QueryPerfCounter">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="counterId" type="xsd:int" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="QueryPerfCounterResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2:PerfCounterInfo" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

QueryPerfProviderSummary

Returns a ProviderSummary object for a ManagedEntity 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: None

Parameters

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

P Required privilege: System.Read

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" name="QueryPerfProviderSummary">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="entity" type="vim2:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="QueryPerfProviderSummaryResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2:PerfProviderSummary"/>
               </sequence>
            </complexType>
         </element>

RemovePerfInterval

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" name="RemovePerfInterval">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="samplePeriod" type="xsd:int"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="RemovePerfIntervalResponse">
            <complexType/>
         </element>

UpdatePerfInterval

Updates a historical interval configuration if it exists.

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.

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" name="UpdatePerfInterval">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="interval" type="vim2:PerfInterval"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="UpdatePerfIntervalResponse">
            <complexType/>
         </element>