VirtualBox Main API
Public Member Functions | Public Attributes | List of all members
IPerformanceCollector Interface Reference

The IPerformanceCollector interface represents a service that collects and stores performance metrics data. More...

Public Member Functions

void getMetrics (in wstring[] metricNames, in $unknown[] objects,[retval] out IPerformanceMetric[] metrics)
 Returns parameters of specified metrics for a set of objects.
void setupMetrics (in wstring[] metricNames, in $unknown[] objects, in unsigned long period, in unsigned long count,[retval] out IPerformanceMetric[] affectedMetrics)
 Sets parameters of specified base metrics for a set of objects.
void enableMetrics (in wstring[] metricNames, in $unknown[] objects,[retval] out IPerformanceMetric[] affectedMetrics)
 Turns on collecting specified base metrics.
void disableMetrics (in wstring[] metricNames, in $unknown[] objects,[retval] out IPerformanceMetric[] affectedMetrics)
 Turns off collecting specified base metrics.
void queryMetricsData (in wstring[] metricNames, in $unknown[] objects, out wstring[] returnMetricNames, out $unknown[] returnObjects, out wstring[] returnUnits, out unsigned long[] returnScales, out unsigned long[] returnSequenceNumbers, out unsigned long[] returnDataIndices, out unsigned long[] returnDataLengths,[retval] out long[] returnData)
 Queries collected metrics data for a set of objects.

Public Attributes

readonly attribute wstring[] metricNames
 Array of unique names of metrics.

Detailed Description

The IPerformanceCollector interface represents a service that collects and stores performance metrics data.

  Performance metrics are associated with objects of interfaces like IHost
  and IMachine. Each object has a distinct set of performance metrics. The
  set can be obtained with @link IPerformanceCollector::getMetrics IPerformanceCollector::getMetrics@endlink<b></b>.

  Metric data is collected at the specified intervals and is retained
  internally. The interval and the number of retained samples can be set
  with @link IPerformanceCollector::setupMetrics IPerformanceCollector::setupMetrics@endlink<b></b>. Both metric data
  and collection settings are not persistent, they are discarded as soon as
  VBoxSVC process terminates. Moreover, metric settings and data associated
  with a particular VM only exist while VM is running. They disappear as
  soon as VM shuts down. It is not possible to set up metrics for machines
  that are powered off. One needs to start VM first, then set up metric
  collection parameters.

  Metrics are organized hierarchically, with each level separated by a
  slash (/) character. Generally, the scheme for metric names is like this:

  <tt>Category/Metric[/SubMetric][:aggregation]</tt>

  "Category/Metric" together form the base metric name. A base metric is
  the smallest unit for which a sampling interval and the number of
  retained samples can be set. Only base metrics can be enabled and
  disabled. All sub-metrics are collected when their base metric is
  collected. Collected values for any set of sub-metrics can be queried
  with @link IPerformanceCollector::queryMetricsData IPerformanceCollector::queryMetricsData@endlink<b></b>.

  For example "CPU/Load/User:avg" metric name stands for the "CPU"
  category, "Load" metric, "User" submetric, "average" aggregate. An
  aggregate function is computed over all retained data. Valid aggregate
  functions are:

  <ul>

avg – average min – minimum max – maximum

  When setting up metric parameters, querying metric data, enabling or
  disabling metrics wildcards can be used in metric names to specify a
  subset of metrics. For example, to select all CPU-related metrics
  use <tt>CPU/*</tt>, all averages can be queried using <tt>*:avg</tt> and
  so on. To query metric values without aggregates <tt>*:</tt> can be used.

  The valid names for base metrics are:

  <ul>

CPU/Load CPU/MHz RAM/Usage RAM/VMM

  The general sequence for collecting and retrieving the metrics is:
  <ul>

Obtain an instance of IPerformanceCollector with IVirtualBox::performanceCollector Allocate and populate an array with references to objects the metrics will be collected for. Use references to IHost and IMachine objects. Allocate and populate an array with base metric names the data will be collected for. Call IPerformanceCollector::setupMetrics. From now on the metric data will be collected and stored. Wait for the data to get collected. Allocate and populate an array with references to objects the metric values will be queried for. You can re-use the object array used for setting base metrics. Allocate and populate an array with metric names the data will be collected for. Note that metric names differ from base metric names. Call IPerformanceCollector::queryMetricsData. The data that have been collected so far are returned. Note that the values are still retained internally and data collection continues.

  For an example of usage refer to the following files in VirtualBox SDK:
  <ul>

Java: bindings/webservice/java/jax-ws/samples/metrictest.java Python: bindings/xpcom/python/sample/shellcommon.py

Interface ID:
{E22E1ACB-AC4A-43BB-A31C-17321659B0C6}

Member Function Documentation

void IPerformanceCollector::getMetrics ( in wstring[]  metricNames,
in $unknown[]  objects,
[retval] out IPerformanceMetric[]  metrics 
)

Returns parameters of specified metrics for a set of objects.

Parameters
metricNamesMetric name filter. Currently, only a comma-separated list of metrics is supported.
objectsSet of objects to return metric parameters for.
metricsArray of returned metric parameters.
Note
Null metrics array means all metrics. Null object array means all existing objects.
void IPerformanceCollector::setupMetrics ( in wstring[]  metricNames,
in $unknown[]  objects,
in unsigned long  period,
in unsigned long  count,
[retval] out IPerformanceMetric[]  affectedMetrics 
)

Sets parameters of specified base metrics for a set of objects.

Returns an array of IPerformanceMetric describing the metrics have been affected.

Parameters
metricNamesMetric name filter. Comma-separated list of metrics with wildcard support.
objectsSet of objects to setup metric parameters for.
periodTime interval in seconds between two consecutive samples of performance data.
countNumber of samples to retain in performance data history. Older samples get discarded.
affectedMetricsArray of metrics that have been modified by the call to this method.
Note
Null or empty metric name array means all metrics. Null or empty object array means all existing objects. If metric name array contains a single element and object array contains many, the single metric name array element is applied to each object array element to form metric/object pairs.
void IPerformanceCollector::enableMetrics ( in wstring[]  metricNames,
in $unknown[]  objects,
[retval] out IPerformanceMetric[]  affectedMetrics 
)

Turns on collecting specified base metrics.

Returns an array of IPerformanceMetric describing the metrics have been affected.

Parameters
metricNamesMetric name filter. Comma-separated list of metrics with wildcard support.
objectsSet of objects to enable metrics for.
affectedMetricsArray of metrics that have been modified by the call to this method.
Note
Null or empty metric name array means all metrics. Null or empty object array means all existing objects. If metric name array contains a single element and object array contains many, the single metric name array element is applied to each object array element to form metric/object pairs.
void IPerformanceCollector::disableMetrics ( in wstring[]  metricNames,
in $unknown[]  objects,
[retval] out IPerformanceMetric[]  affectedMetrics 
)

Turns off collecting specified base metrics.

Returns an array of IPerformanceMetric describing the metrics have been affected.

Parameters
metricNamesMetric name filter. Comma-separated list of metrics with wildcard support.
objectsSet of objects to disable metrics for.
affectedMetricsArray of metrics that have been modified by the call to this method.
Note
Null or empty metric name array means all metrics. Null or empty object array means all existing objects. If metric name array contains a single element and object array contains many, the single metric name array element is applied to each object array element to form metric/object pairs.
void IPerformanceCollector::queryMetricsData ( in wstring[]  metricNames,
in $unknown[]  objects,
out wstring[]  returnMetricNames,
out $unknown[]  returnObjects,
out wstring[]  returnUnits,
out unsigned long[]  returnScales,
out unsigned long[]  returnSequenceNumbers,
out unsigned long[]  returnDataIndices,
out unsigned long[]  returnDataLengths,
[retval] out long[]  returnData 
)

Queries collected metrics data for a set of objects.

    The data itself and related metric information are returned in seven
    parallel and one flattened array of arrays. Elements of
    <tt>returnMetricNames, returnObjects, returnUnits, returnScales,
    returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
    the same index describe one set of values corresponding to a single
    metric.

    The <tt>returnData</tt> parameter is a flattened array of arrays. Each
    start and length of a sub-array is indicated by
    <tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
    value for metric <tt>metricNames[i]</tt> is at
    <tt>returnData[returnIndices[i]]</tt>.
Parameters
metricNamesMetric name filter. Comma-separated list of metrics with wildcard support.
objectsSet of objects to query metrics for.
returnMetricNamesNames of metrics returned in returnData.
returnObjectsObjects associated with metrics returned in returnData.
returnUnitsUnits of measurement for each returned metric.
returnScalesDivisor that should be applied to return values in order to get floating point values. For example: (double)returnData[returnDataIndices[0]+i] / returnScales[0] will retrieve the floating point value of i-th sample of the first metric.
returnSequenceNumbersSequence numbers of the first elements of value sequences of particular metrics returned in returnData. For aggregate metrics it is the sequence number of the sample the aggregate started calculation from.
returnDataIndicesIndices of the first elements of value sequences of particular metrics returned in returnData.
returnDataLengthsLengths of value sequences of particular metrics.
returnDataFlattened array of all metric data containing sequences of values for each metric.
Note
Null or empty metric name array means all metrics. Null or empty object array means all existing objects. If metric name array contains a single element and object array contains many, the single metric name array element is applied to each object array element to form metric/object pairs.
Data collection continues behind the scenes after call to queryMetricsData. The return data can be seen as the snapshot of the current state at the time of queryMetricsData call. The internally kept metric values are not cleared by the call. This allows querying different subsets of metrics or aggregates with subsequent calls. If periodic querying is needed it is highly suggested to query the values with interval*count period to avoid confusion. This way a completely new set of data values will be provided by each query.

Member Data Documentation

readonly attribute wstring [] IPerformanceCollector::metricNames

Array of unique names of metrics.

This array represents all metrics supported by the performance collector. Individual objects do not necessarily support all of them. IPerformanceCollector::getMetrics can be used to get the list of supported metrics for a particular object.