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 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:

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:

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 PPerformanceDescription

The static description strings.
historicalInterval* PPerfInterval[]

Retrieves all configured historical archive sampling intervals. Refer to HistoricalInterval for a description of historical intervals.
perfCounter* PPerfCounterInfo[]

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 following example is valid:

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

The following example is invalid because the second length is shorter than the first one:
Required Privileges
Performance.ModifyIntervals

Parameters

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

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
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 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

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

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
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

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

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

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
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

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

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

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
PerfCompositeMetricThe metric values for the specified entity and its holding 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



QueryPerfCounter

Retrieves counter information for the list of counter IDs passed in.
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

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:
  1. 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.
  2. 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.
  3. 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).
  4. Level 4: Includes all metrics supported by VirtualCenter, including maximum and minimum rollup types.
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

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
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

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

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



Return Value

Type Description
PerfProviderSummary

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 VI 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 particular 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

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:
  1. The sampling period of the "Past Day" interval can be reduced from 5 minutes to 1, 2 or 3 minutes.
  2. The length of the "Past Day" interval can be increased from 1 day up to 3 days.
  3. The length of the "Past Year" interval can be increased from 1 year up to 3 years.
  4. 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.
  5. 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

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

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
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