Scripting Object - VcPerformanceManager

Scripting-object corresponding to
PerformanceManager
Attribute of
VcSdkConnection, VcServiceContent

Scripting 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" ({@link PerformanceManager.ProviderSummary}) is any managed object that generates utilization or other performance metrics. Performance providers include {@link vim.ManagedEntity managed entities}, such as {@link vim.HostSystem hosts}, {@link vim.VirtualMachine virtual machines}, {@link vim.ComputeResource compute resources}, {@link vim.ResourcePool resource pools}, {@link vim.Datastore datastores}, and {@link vim.Network 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 {@link PerformanceManager.CounterInfo counters} that provides metadata about its available {@link PerformanceManager.EntityMetric metrics}. Each counter has a unique {@link PerformanceManager.CounterInfo#key}, referred to as the counterId. The actual performance metrics generated at runtime are identified by this {@link PerformanceManager.MetricId#counterId}. Counters are organized by {@link PerformanceManager.CounterInfo#groupInfo groups} of finite system resources, such as memory, CPU, disk, and so on. The links in this list contain documentation for performance counters, by {@link PerformanceManager.CounterInfo#groupInfo group}. Each page contains a table that includes data extracted from instances of the {@link PerformanceManager.CounterInfo} 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 {@link PerformanceManager}.

Attributes

Name Type Description
descriptionVcPerformanceDescription

@since VI API 2.5
historicalIntervalVcPerfInterval []

@since VI API 2.5
idString

@since Unknown
morefVcManagedObjectReference

returns the ManagedObjectReference of this ManagedObject @since Unknown
perfCounterVcPerfCounterInfo []

@since VI API 2.5
sdkConnectionVcSdkConnection

@since Unknown
sdkIdString

@since Unknown
typeStringDeprecated.

Returns the name for the this managed object's vim type @since Unknown
vimHostVcSdkConnection

@since Unknown
vimIdString

@since Unknown
vimTypeString

@since Unknown

Methods

Methods defined in this Scripting Object
_getRef, createPerfInterval, createTrigger, perfDisableStat, perfEnableStat, queryAvailablePerfMetric, queryPerf, queryPerfComposite, queryPerfCounter, queryPerfCounterByLevel, queryPerfCounterInt, queryPerfProviderSummary, removePerfInterval, resetCounterLevelMapping, summarizeStats, updateCounterLevelMapping, updatePerfInterval

perfDisableStat

Exclude a counter or a set of counters from the counters collection of this {@link PerformanceManager PerformanceManager}.

This method is provided in order to be used by the clients, when a reduction in the collected samples set is needed, because of a performance issues.

The changes made by this method are applied to the collection of counters for the current instance of {@link PerformanceManager PerformanceManager} and are visible for all clients. @since vSphere API 5.0

Parameters

NameTypeDescription
arg0Number []


Return Value

Type Description
None

_getRef

@since Unknown

Parameters

NameTypeDescription
None

Return Value

Type Description
VcManagedObjectReference

removePerfInterval

Removes an interval from the list. @since VI API 2.5

Parameters

NameTypeDescription
arg0Number


Return Value

Type Description
None

queryPerfCounterInt

Return all internal counters, supported by this {@link PerformanceManager PerformanceManager}. Every counter is represented by {@link PerformanceManager.CounterInfoInt PerfCounterInfoInt} data object, provides information about the enable/disable status of the counter, in addition to the information, already provided by {@link PerformanceManager.CounterInfo PerfCounterInfo}. @since vSphere API 5.0

Parameters

NameTypeDescription
None

Return Value

Type Description
VcPerfCounterInfoInt []

perfEnableStat

Enable a counter or a set of counters in the counters collection of this {@link PerformanceManager PerformanceManager}.

In order to be available for the clients, a counter should be enabled. That is, {@link PerformanceManager.CounterInfoInt#enabled PerfCounterInfoInt.enabled} should be true. Note that some of the provided counters are already enabled by default - they have {@link PerformanceManager.CounterInfoInt#enabledByDefault PerfCounterInfoInt.enabledByDefault} set to true.

The changes made by this method are applied to the collection of counters for the current instance of {@link PerformanceManager PerformanceManager} and are visible for all clients. @since vSphere API 5.0

Parameters

NameTypeDescription
arg0Number []


Return Value

Type Description
None

queryPerfProviderSummary

Retrieves the {@link PerformanceManager.ProviderSummary} data object that defines the capabilities of the specified managed object with respect to statistics, such as whether it supports current or summary statistics. @since VI API 2.5

Parameters

NameTypeDescription
arg0VcManagedObject


Return Value

Type Description
VcPerfProviderSummary

updatePerfInterval

Modifies VirtualCenter Server's built-in {@link HistoricalInterval historical intervals}, within certain limits.

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 {@link HistoricalInterval 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 {@link HistoricalInterval#samplingPeriod} from 5 minutes to 1, 2, or 3 minutes.
[4]  Can increase this interval’s {@link HistoricalInterval#length} from 1 day to 2 or 3 days.
[5]  Can increase interval’s {@link HistoricalInterval#length} from 1 year to 2 or 3 years.

See {@link HistoricalInterval} for information about the four default intervals for VirtualCenter Server. @since VI API 2.5

Parameters

NameTypeDescription
arg0VcPerfInterval


Return Value

Type Description
None

queryAvailablePerfMetric

Retrieves all performance counters for the specified {@link ExtensibleManagedObject managed object} generated during a specified period of time. The time period can be specified using beginTime, endTime, or by interval ID. @since VI API 2.5

Parameters

NameTypeDescription
arg0VcManagedObject

arg1Date

arg2Date

arg3Number


Return Value

Type Description
VcPerfMetricId []

queryPerfCounter

Retrieves counter information for the specified list of counter IDs. @since VI API 2.5

Parameters

NameTypeDescription
arg0Number []


Return Value

Type Description
VcPerfCounterInfo []

summarizeStats

Summarizes performance statistics at the specified interval with startTime specifying the start of the first interval boundary. @since VI API 2.5

Parameters

NameTypeDescription
arg0VcPerfQuerySpec []


Return Value

Type Description
VcPerfEntityMetricCSV []

createTrigger

@since Unknown

Parameters

NameTypeDescription
timeoutNumber

filterString

conditionString

filterToSyncString


Return Value

Type Description
Trigger

queryPerfCounterByLevel

Retrieves the set of counters that are available at a specified collection {@link HistoricalInterval#level}. The collection level determines the statistics that get stored in VirtualCenter. See {@link HistoricalInterval} for more information about VirtualCenter Server historical statistics collection. @since VI API 2.5

Parameters

NameTypeDescription
arg0Number


Return Value

Type Description
VcPerfCounterInfo []

createPerfInterval

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. @since VI API 2.5

Parameters

NameTypeDescription
arg0VcPerfInterval


Return Value

Type Description
None

resetCounterLevelMapping

Restores a set of performance counters to the default level of data collection. See the performance counter tables for the default collection level for individual counters. @since vSphere API 4.1

Parameters

NameTypeDescription
arg0Number []


Return Value

Type Description
None

queryPerfComposite

Retrieves a {@link PerformanceManager.CompositeEntityMetric} 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 {@link PerformanceManager.CompositeEntityMetric} object.

Use this operation to obtain statistics for a {@link vim.HostSystem host} and its associated {@link vim.VirtualMachine 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 {@link vim.HostSystem} managed entities only. @since VI API 2.5

Parameters

NameTypeDescription
arg0VcPerfQuerySpec


Return Value

Type Description
VcPerfCompositeMetric

updateCounterLevelMapping

Changes the level of data collection for a set of performance counters. See the performance counter tables for the default collection level for individual counters.

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.{@link vim.PerformanceManager#historicalInterval}) and the collection levels specified for individual performance counters ({@link vim.PerformanceManager.CounterInfo}.{@link vim.PerformanceManager.CounterInfo#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.{@link vim.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 {@link vim.PerformanceManager.CounterInfo#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 {@link vim.PerformanceManager#updateHistoricalInterval} 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 {@link vim.PerformanceManager#resetCounterLevelMapping} method. @since vSphere API 4.1

Parameters

NameTypeDescription
arg0VcPerformanceManagerCounterLevelMapping []


Return Value

Type Description
None

queryPerf

Retrieves the performance metrics for the specified entity (or entities) based on the properties specified in the {@link PerformanceManager.QuerySpec} data object.

Query Performance for VirtualCenter Server
@since VI API 2.5

Parameters

NameTypeDescription
arg0VcPerfQuerySpec []


Return Value

Type Description
VcPerfEntityMetricBase []