8 VBoxManage reference
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 5 most current samples, the following command can be used:
VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage
Specifying
0
as either the interval or as the number of retained samples disables
metric collection again. Note that the
VBoxManage metrics setup
subcommand
discards all samples that may have been previously collected for the specified set of
objects and metrics.
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
or/and a list of metrics. If no objects or metrics are given in the parameters, the sub-
commands 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 met-
rics. 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”, you can use the following command:
VBoxManage query test CPU/Load/User,CPU/Load/Kernel
The following list summarizes the available subcommands:
list
This subcommand shows the parameters of the currently existing metrics. Note
that VM-specific metrics are only available when a particular VM is running.
setup
This subcommand 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
-list
option shows which
metrics have been modified as the result of the command execution.
query
This subcommand retrieves and displays the currently retained metric data.
123
