Managed Object - PerformanceManager

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


Managed Object Description

This managed object type provides the service interface for obtaining statistical data about various aspects of system performance, as generated and maintained by the system's performance providers. A "performance provider" (PerfProviderSummary) is any managed object that generates utilization or other performance metrics. Performance providers include managed entities, such as hosts, virtual machines, compute resources, resource pools, datastores, and networks. Performance providers also include physical or virtual devices associated with these objects, such as virtual host-bus adapters and network-interface controllers (NICs)

Performance Counters
Each performance provider—the instrumented device or entity—has its own set of counters that provides metadata about its available metrics. Each counter has a unique key, referred to as the counterId. The actual performance metrics generated at runtime are identified by this counterId. Counters are organized by groups of finite system resources, such as memory, CPU, disk, and so on. The links in this list contain documentation for performance counters, by group. Each page contains a table that includes data extracted from instances of the PerfCounterInfo data object, including the counter name, its Label, Unit, StatsType, RollupType, and Level:

Other performance-counter groups, in addition to those listed here, exist on the system. However, only the counter groups listed are considered of possible interest to third-party developers.

Obtaining Metadata and Metrics
This interface provides these query operations:

Product and Version Specifics
Some differences between ESX and vCenter Server implementations of this interface include:

See the Programming Guide for more information about using PerformanceManager.

Properties

Name Type Description
description PPerformanceDescription

The static description strings.
historicalInterval* PPerfInterval[]

A list of intervals configured on the system.
perfCounter* PPerfCounterInfo[]

A list of 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 API 2.5, use UpdatePerfInterval. The default historical intervals can be modified, but they cannot be created.

Adds a new historical interval. Sampling period for new interval must be a multiple of an existing interval; must comprise a longer period of time; and must be uniquely named.

Required Privileges
Performance.ModifyIntervals

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the PerformanceManager used to make the method call.
intervalIdPerfInterval

A custom interval, specified as the number of seconds to hold data in the database, a user-specified unique name, and a sampling period (in seconds).

Return Value

Type Description
None

Faults

Type Description
InvalidArgumentThrown if the set of arguments passed to the function is not specified correctly.
RuntimeFaultThrown 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



QueryAvailablePerfMetric

Retrieves all performance counters for the specified managed object generated during a specified period of time. The time period can be specified using beginTime, endTime, or by interval ID.
Required Privileges
System.Read

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the PerformanceManager used to make the method call.
entityManagedObjectReference

The managed object that provides performance metrics.
beginTime*xsd:dateTime

Starting time (server time) for a period of time from which to return available metrics. If not specified, defaults to oldest available metric for the specified entity.
endTime*xsd:dateTime

Ending time (server time) for a period of time from which to return available performance metrics. If not specified, defaults to the most recently generated metric for the specified entity.
intervalId*xsd:int

Period of time from which to retrieve metrics, defined by intervalId (rather than beginTime or endTime). Valid intervalIds include: If this parameter is not specified, the system returns available metrics for historical statistics.
*Need not be set

Return Value

Type Description
PerfMetricId[]An array of metrics, each of which comprises a counterId and an name.

Faults

Type Description
InvalidArgumentThrown if the set of arguments passed to the function is not specified correctly.
RuntimeFaultThrown 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



QueryPerf

Retrieves the performance metrics for the specified entity (or entities) based on the properties specified in the PerfQuerySpec data object.

Query Performance for VirtualCenter Server

Required Privileges
System.View

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the PerformanceManager used to make the method call.
querySpecPerfQuerySpec[]

An array of PerfQuerySpec objects. Each PerfQuerySpec object specifies a managed object reference for an entity, plus optional criteria for filtering results. Only metrics for entities that can be resolved and that are valid performance providers are returned in any result.

Each PerfQuerySpec object in the array submitted in this operation can query for different metrics. Or, select all types of statistics for a single managed entity.

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
InvalidArgumentThrown if the set of arguments passed to the function is not specified correctly.
RuntimeFaultThrown 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



QueryPerfComposite

Retrieves a PerfCompositeMetric data object that comprises statistics for the specified entity and its children entities. Only metrics for the first level of descendents are included in the PerfCompositeMetric object.

Use this operation to obtain statistics for a host and its associated virtual machines, for example.

Requires system.read privilege for every virtual machine on the target host, or the query fails with the “NoPermission” fault. Suported for HostSystem managed entities only.

Required Privileges
System.View

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the PerformanceManager used to make the method call.
querySpecPerfQuerySpec

A PerfQuerySpec object specifying the query parameters. This PerfQuerySpec object specifies a managed object for which composite statistics should be retrieved, with specific optional criteria for filtering the results.

This PerfQuerySpec requires a valid metricId property that specifies a metric that is available, in common, to the entity and its children. If the specified metricId is not available to the entity and its children, it is ignored.


Return Value

Type Description
PerfCompositeMetricThe metric values for the specified entity and its associated entities for a single interval.

Faults

Type Description
InvalidArgumentThrown if the set of arguments passed to the function is not specified correctly.
RuntimeFaultThrown 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



QueryPerfCounter

Retrieves counter information for the specified list of counter IDs.
Required Privileges
System.View

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the PerformanceManager used to make the method call.
counterIdxsd: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
InvalidArgumentThrown if the set of arguments passed to the function is not specified correctly.
RuntimeFaultThrown 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



QueryPerfCounterByLevel

Retrieves the set of counters that are available at a specified collection level. The collection level determines the statistics that get stored in VirtualCenter. See PerfInterval for more information about VirtualCenter Server historical statistics collection.

Required Privileges
System.View
Since
VI API 2.5

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the PerformanceManager used to make the method call.
levelxsd:int

A number between 1 and 4 that specifies the collection level.

Return Value

Type Description
PerfCounterInfo[]An array of PerfCounterInfo objects that define the set of counters having the specified level number available for the entity.

Faults

Type Description
InvalidArgumentThrown if an invalid level is specified.
RuntimeFaultThrown 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



QueryPerfProviderSummary

Retrieves the PerfProviderSummary data object that defines the capabilities of the specified managed object with respect to statistics, such as whether it supports current or summary statistics.
Required Privileges
System.Read

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the PerformanceManager used to make the method call.
entityManagedObjectReference

Reference to a managed object that provides performance data. If the entity specified by managed object reference is not a performance provider, an "InvalidArgument" exception is thrown.

Return Value

Type Description
PerfProviderSummaryA data object containing metadata about the entity as a performance provider, such as the type of metrics (real-time, summary, or both) it generates and the refreshRate.

Faults

Type Description
RuntimeFaultThrown 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



RemovePerfInterval

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

Removes an interval from the list.
Required Privileges
Performance.ModifyIntervals

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the PerformanceManager used to make the method call.
samplePeriodxsd:int

The sampling period, in seconds, for the specified interval being removed.

Return Value

Type Description
None

Faults

Type Description
InvalidArgumentThrown if the set of arguments passed to the function is not specified correctly.
RuntimeFaultThrown 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



UpdatePerfInterval

Modifies VirtualCenter Server's built-in historical intervals, within certain limits.

Supported Modifications

keysamplingPeriodlengthname level [1] enabled [2]
1300 [3] 86400 [4] Past day1true
21800604800Past week1 true
372002592000 Past month1true
466400 31536000 [5]Past year1true

[1]  The collection level for the historical intervals can be changed. However, the level specified for a lower-numbered interval cannot be smaller than that of a larger interval.
[2]  An interval can be disabled. By default, all four intervals are enabled. Disabling an interval disables all higher intervals. For example, disabling interval 3 (“Past month”) also disables interval 4 (“Past year”).
[3]  Can reduce this interval’s samplingPeriod from 5 minutes to 1, 2, or 3 minutes.
[4]  Can increase this interval’s length from 1 day to 2 or 3 days.
[5]  Can increase interval’s length from 1 year to 2 or 3 years.

See PerfInterval for information about the four default intervals for VirtualCenter Server.

Required Privileges
Performance.ModifyIntervals

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the PerformanceManager used to make the method call.
intervalPerfInterval

The historical interval being modified, a complete data object comprising values for enabled, interval ID, length of time to maintain statistics for this interval in the database, level, name, and samplingPeriod properties.

Return Value

Type Description
None

Faults

Type Description
InvalidArgumentThrown 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.
RuntimeFaultThrown 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