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:

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. 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* 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, QueryPerfProviderSummary, RemovePerfInterval, UpdatePerfInterval

CreatePerfInterval

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 ManagedEntity between the optional beginTime and endTime. These are the performance statistics that are available for the given time interval.
Required Privileges
None

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the PerformanceManager used to make the method call.
entity PManagedObjectReference
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
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 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
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 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
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



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

NameTypeDescription
_thisManagedObjectReference A reference to the PerformanceManager used to make the method call.
entity PManagedObjectReference
to a ManagedEntity
P Required privilege: System.Read

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

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 a historical interval configuration if it exists.
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.

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