| Local Properties | Local Methods | |
Managed Object Types | Data Object Types | All Properties | All Methods |
Performance Counters
Each
performance providerthe instrumented device or entityhas 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
groupInfo of finite system
resources, such as memory, CPU, disk, and
so on. The links in this list contain documentation for performance
counters, by groupInfo. 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 P | PerformanceDescription |
The static description strings.
|
historicalInterval* P | PerfInterval[] |
A list of intervals configured on the
system.
|
perfCounter* P | PerfCounterInfo[] |
A list of all supported performance counters in the system.
|
Methods
Methods defined in this Managed Object |
---|
CreatePerfInterval, QueryAvailablePerfMetric, QueryPerf, QueryPerfComposite, QueryPerfCounter, QueryPerfCounterByLevel, QueryPerfProviderSummary, RemovePerfInterval, ResetCounterLevelMapping, UpdateCounterLevelMapping, UpdatePerfInterval |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the PerformanceManager used to make the method call. |
intervalId P | PerfInterval |
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).
Since 2.0 |
Return Value
Type | Description |
---|---|
None |
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. |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the PerformanceManager used to make the method call. |
entity P | ManagedObjectReference |
The entity that
provides performance metrics.
Since 2.0 |
beginTime* P | 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.
Since 2.0 |
endTime* P | 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.
Since 2.0 |
intervalId* P | xsd:int |
Period of time from which to retrieve metrics, defined by intervalId
(rather than beginTime or endTime). Valid intervalIds include:
|
Return Value
Type | Description |
---|---|
PerfMetricId[] | An array of metrics, each of which comprises a counterId and an instance. |
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. |
Events
Type | |
---|---|
None |
Query Performance for VirtualCenter Server
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the PerformanceManager used to make the method call. |
querySpec P | PerfQuerySpec[] |
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. Since 2.0 |
Return Value
Type | Description |
---|---|
PerfEntityMetricBase[] | The metric values for the specified entity or entities. |
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. |
Events
Type | |
---|---|
None |
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.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the PerformanceManager used to make the method call. |
querySpec P | PerfQuerySpec |
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. Since 2.0 |
Return Value
Type | Description |
---|---|
PerfCompositeMetric | The metric values for the specified entity and its associated entities for a single interval. |
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. |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the PerformanceManager used to make the method call. |
counterId P | xsd:int[] |
An array of one or more counterId representing performance counters for which information is
being retrieved.
Since 2.0 |
Return Value
Type | Description |
---|---|
PerfCounterInfo[] | An array consisting of performance counter information for the specified counterIds. |
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. |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the PerformanceManager used to make the method call. |
level P | xsd:int |
A number between 1 and 4 that specifies the collection level.
Since VI API 2.5 |
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 |
---|---|
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the PerformanceManager used to make the method call. |
entity P | ManagedObjectReference |
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.
Since 2.0 |
Return Value
Type | Description |
---|---|
PerfProviderSummary | A 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 |
---|---|
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the PerformanceManager used to make the method call. |
samplePeriod P | xsd:int |
The sampling period, in seconds, for the specified interval being
removed.
Since 2.0 |
Return Value
Type | Description |
---|---|
None |
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. |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the PerformanceManager used to make the method call. |
counters P | xsd:int[] |
An array of counter ids.
Since vSphere API 4.1 |
Return Value
Type | Description |
---|---|
None |
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. |
Events
Type | |
---|---|
None |
Important:
Consider the performance and storage consequences of using this method. You may cause a significant increase in data collection and storage, along with a corresponding decrease in performance. vCenter Server performance and database storage requirements depend on the collection levels defined for the performance intervals (PerformanceManager.HistoricalInterval) and the collection levels specified for individual performance counters (PerfCounterInfo.level).
Performance Counter Data Collection
vSphere defines four levels of data collection for performance counters. Each performance counter specifies a level for collection. The historical performance intervals (PerformanceManager.HistoricalInterval) define the sampling period and length for a particular collection level.
The amount of data collected for a performance counter depends on the performance interval and on the type of entity for which the counter is defined. For example, a datastore counter such as datastoreIops (the aggregate number of IO operations on the datastore) will generate a data set that corresponds to the number of datastores on a host. If a vCenter Server manages a large number of hosts with a large number of datastores, the Server will collect a large amount of data.
There are other counters for which the vCenter Server collects a relatively smaller amount of data. For example, memory counters are collected as a single counter per virtual machine and a single counter per host.
Performance Counter Data Storage
The performance interval collection level defines the set of counters for which the vCenter Server stores performance data. The Server will store data for counters at the specified level and for counters at all lower levels.
By default, all the performance intervals specify collection level one. Using these defaults, the vCenter Server stores performance counter data in the vCenter database for all counters that specify collection level one. It does not store data for counters that specify collection levels two through four.
Performance Manager Method Interaction
You can use the UpdateCounterLevelMapping method to change the collection level for individual counters. You can also use the UpdatePerfInterval method to change the collection level for the system-defined performance intervals. These methods can cause a significant increase in the amount of data collected and stored in the vCenter database.
You may cause a significant increase in data collection and storage along with a corresponding decrease in performance under the following conditions:
To restore counter levels to default settings use the ResetCounterLevelMapping method.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the PerformanceManager used to make the method call. |
counterLevelMap P | PerformanceManagerCounterLevelMapping[] |
An array of PerformanceManagerCounterLevelMapping objects. The
levels for the counters passed in are changed to the passed in values. If
the optional aggregateLevel field is left unset then only the
perDeviceLevel is configured. If the optional perDeviceLevel is left
unset then only the aggregateLevel is configured. If there are multiple
entries in the passed in array for the same counterId being updated then
the last entry containing the counterId takes effect.
Since vSphere API 4.1 |
Return Value
Type | Description |
---|---|
None |
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. |
Events
Type | |
---|---|
None |
Supported Modifications
key | samplingPeriod | length | name | level [1] | enabled [2] |
---|---|---|---|---|---|
1 | 300 [3] | 86400 [4] | Past day | 1 | true |
2 | 1800 | 604800 | Past week | 1 | true |
3 | 7200 | 2592000 | Past month | 1 | true |
4 | 86400 | 31536000 [5] | Past year | 1 | true |
[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 intervals samplingPeriod from 5 minutes to 1, 2, or 3
minutes.
[4] Can increase this intervals length from 1 day to 2 or 3 days.
[5] Can increase intervals length from 1 year to 2 or 3 years.
See PerfInterval for information about the four default intervals for VirtualCenter Server.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the PerformanceManager used to make the method call. |
interval P | PerfInterval |
The historical interval being modified, a
complete data object comprising values for enabled, key,
length of time to maintain statistics for this
interval in the database, level, name, and samplingPeriod
properties.
Since 2.0 |
Return Value
Type | Description |
---|---|
None |
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. |
Events
Type | |
---|---|
None |
Top of page | Local Properties | Local Methods | |
Managed Object Types | Data Object Types | All Properties | All Methods |