This command supports monitoring the usage of system resources.
Resources are represented by various metrics associated with the
host system or a particular VM. For example, the host system has a
CPU/Load/User metric that shows
the percentage of time CPUs spend executing in user mode over a
specific sampling period.
Metric data is collected and retained internally. It may be
retrieved at any time with the VBoxManage metrics
query subcommand. The data is available as long as the
background VBoxSVC process is
alive. That process terminates shortly after all VMs and frontends
have been closed.
By default no metrics are collected at all. Metrics collection does not start until VBoxManage metrics setup is invoked with a proper sampling interval and the number of metrics to be retained. The interval is measured in seconds. For example, to enable collecting the host processor and memory usage metrics every second and keeping the five most current samples, the following command can be used:
VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage
Metric collection can only be enabled for started VMs. Collected
data and collection settings for a particular VM will disappear as
soon as it shuts down. Use the VBoxManage metrics
list subcommand to see which metrics are currently
available. You can also use the --list option
with any subcommand that modifies metric settings to find out
which metrics were affected.
Note that the VBoxManage metrics setup subcommand discards all samples that may have been previously collected for the specified set of objects and metrics.
To enable or disable metrics collection without discarding the
data, VBoxManage metrics enable and
VBoxManage metrics disable subcommands can be
used. Note that these subcommands expect metrics as parameters,
not submetrics such as CPU/Load
or RAM/Usage. In other words
enabling CPU/Load/User while
disabling CPU/Load/Kernel is not
supported.
The host and VMs have different sets of associated metrics. Available metrics can be listed with VBoxManage metrics list subcommand.
A complete metric name may include an aggregate function. The name
has the following form:
Category/Metric[/SubMetric][:aggregate].
For example, RAM/Usage/Free:min
stands for the minimum amount of available memory over all
retained data if applied to the host object.
Subcommands may apply to all objects and metrics or can be limited
to one object and a list of metrics. If no objects or metrics are
given in the parameters, the subcommands will apply to all
available metrics of all objects. You may use an asterisk
"*" to explicitly specify that
the command should be applied to all objects or metrics. Use
host as the object name to limit
the scope of the command to host-related metrics. To limit the
scope to a subset of metrics, use a metric list with names
separated by commas.
For example, to query metric data on the CPU time spent in user
and kernel modes by the virtual machine named
test, use the following command:
VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel
The following list summarizes the available subcommands:
-
list Shows the parameters of the currently existing metrics. Note that VM-specific metrics are only available when a particular VM is running.
-
setup Sets the interval between taking two samples of metric data and the number of samples retained internally. The retained data is available for displaying with the query subcommand. The
--listoption shows which metrics have been modified as the result of the command execution.-
enable Resumes data collection after it has been stopped with the disable subcommand. Note that specifying submetrics as parameters will not enable underlying metrics. Use
--listto find out if the command worked as expected.-
disable Suspends data collection without affecting collection parameters or collected data. Note that specifying submetrics as parameters will not disable underlying metrics. Use
--listto find out if the command worked as expected.-
query Retrieves and displays the currently retained metric data.
NoteThe query subcommand does not remove or flush retained data. If you query often enough you will see how old samples are gradually being phased out by new samples.
-
collect Sets the interval between taking two samples of metric data and the number of samples retained internally. The collected data is displayed periodically until Ctrl+C is pressed, unless the
--detachoption is specified. With the--detachoption, this subcommand operates the same way assetupdoes. The--listoption shows which metrics match the specified filter.