Sun Microsystems 3.0.0 user manual VBoxManage query test CPU/Load/User,CPU/Load/Kernel

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