VirtualBox

source: vbox/trunk/doc/manual/en_US/man_VBoxManage-metrics.xml@ 103131

Last change on this file since 103131 was 99498, checked in by vboxsync, 19 months ago

manual: Split out the topics of converted manpages into separate files and generate ditamap files for each manpage to avoid needing to hardcode anything in UserManual.xml. This means that the topics inside a manpage can be supressed from the toc, but otoh, they get numbered (with 4.x). The per-topic files are named by refentry/refsect1/refsect2 @id and are currently not cleaned up by 'kmk clean'. [fix] bugref:10302

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 17.5 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3 manpage, user manual, usage: VBoxManage metrics
4-->
5<!--
6 Copyright (C) 2006-2023 Oracle and/or its affiliates.
7
8 This file is part of VirtualBox base platform packages, as
9 available from https://www.virtualbox.org.
10
11 This program is free software; you can redistribute it and/or
12 modify it under the terms of the GNU General Public License
13 as published by the Free Software Foundation, in version 3 of the
14 License.
15
16 This program is distributed in the hope that it will be useful, but
17 WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 General Public License for more details.
20
21 You should have received a copy of the GNU General Public License
22 along with this program; if not, see <https://www.gnu.org/licenses>.
23
24 SPDX-License-Identifier: GPL-3.0-only
25-->
26<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
27 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
28<!ENTITY % all.entities SYSTEM "all-entities.ent">
29%all.entities;
30]>
31<refentry id="vboxmanage-metrics" lang="en">
32 <refentryinfo>
33 <pubdate>$Date: 2023-04-21 02:00:16 +0000 (Fri, 21 Apr 2023) $</pubdate>
34 <title>VBoxManage metrics</title>
35 </refentryinfo>
36
37 <refmeta>
38 <refentrytitle>VBoxManage-metrics</refentrytitle>
39 <manvolnum>1</manvolnum>
40 </refmeta>
41
42 <refnamediv>
43 <refname>VBoxManage-metrics</refname>
44 <refpurpose>monitor system resource usage</refpurpose>
45 <refclass>&product-name;</refclass>
46 </refnamediv>
47
48 <refsynopsisdiv>
49 <cmdsynopsis id="synopsis-vboxmanage-metrics-collect">
50 <command>VBoxManage metrics collect</command>
51 <arg>--detach</arg>
52 <arg>--list</arg>
53 <arg>--period=<replaceable>seconds</replaceable></arg>
54 <arg>--samples=<replaceable>count</replaceable></arg>
55 <group>
56 <arg choice="plain">*</arg>
57 <arg choice="plain">host</arg>
58 <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg>
59 </group>
60 </cmdsynopsis>
61
62 <cmdsynopsis id="synopsis-vboxmanage-metrics-disable">
63 <command>VBoxManage metrics disable</command>
64 <arg>--list</arg>
65 <group>
66 <arg choice="plain">*</arg>
67 <arg choice="plain">host</arg>
68 <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg>
69 </group>
70 </cmdsynopsis>
71
72 <cmdsynopsis id="synopsis-vboxmanage-metrics-enable">
73 <command>VBoxManage metrics enable</command>
74 <arg>--list</arg>
75 <group>
76 <arg choice="plain">*</arg>
77 <arg choice="plain">host</arg>
78 <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg>
79 </group>
80 </cmdsynopsis>
81
82 <cmdsynopsis id="synopsis-vboxmanage-metrics-list">
83 <command>VBoxManage metrics list</command>
84 <group>
85 <arg choice="plain">*</arg>
86 <arg choice="plain">host</arg>
87 <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg>
88 </group>
89 </cmdsynopsis>
90
91 <cmdsynopsis id="synopsis-vboxmanage-metrics-query">
92 <command>VBoxManage metrics query</command>
93 <group>
94 <arg choice="plain">*</arg>
95 <arg choice="plain">host</arg>
96 <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg>
97 </group>
98 </cmdsynopsis>
99
100 <cmdsynopsis id="synopsis-vboxmanage-metrics-setup">
101 <command>VBoxManage metrics setup</command>
102 <arg>--list</arg>
103 <arg>--period <replaceable>seconds</replaceable></arg>
104 <arg>--samples <replaceable>count</replaceable></arg>
105 <group>
106 <arg choice="plain">*</arg>
107 <arg choice="plain">host</arg>
108 <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg>
109 </group>
110 </cmdsynopsis>
111 </refsynopsisdiv>
112
113 <refsect1 id="vboxmanage-metrics-description">
114 <title>Description</title>
115 <para>
116 The <command>VBoxManage metrics</command> command enables you to
117 monitor system resource usage for the host system and for virtual
118 machines (VMs). For example, you can monitor particular metrics,
119 such as the percentage of time CPUs spend executing in user mode
120 (<literal>CPU/Load/User</literal>) over a specified sampling
121 period.
122 </para>
123 <para>
124 While it runs, the <command>VBoxSVC</command> process collects and
125 saves the specified metric data internally. The
126 <command>VBoxSVC</command> process runs until shortly after you
127 close all VMs and frontends. Use the <command>VBoxManage metrics
128 query</command> command to retrieve data at any time.
129 </para>
130 <para>
131 By default, metrics are not collected unless you run the
132 <command>VBoxManage metrics setup</command> command to specify a
133 sampling interval in seconds and the number of metrics to save.
134 </para>
135 <para>
136 Note that you can enable metric collection only for started VMs.
137 Collected data and collection settings for a VM are discarded when
138 the VM shuts down.
139 </para>
140 <refsect2 id="vboxmanage-metrics-description-metrics">
141 <title>Metrics</title>
142 <para>
143 The host and VMs have different sets of associated metrics,
144 which you can view by running the <command>VBoxManage metrics
145 list</command> command.
146 </para>
147 <para>
148 Each metric is represented as a string that is composed of a
149 category and a metric. Optionally, the metric string can include
150 any of the following: a submetric, a sub-submetric, and an
151 aggregate. The metric string has the following format:
152 </para>
153<screen><replaceable>category</replaceable>/<replaceable>metric</replaceable>[/<replaceable>submetric</replaceable>[/<replaceable>sub-submetric</replaceable>]][:<replaceable>aggregate</replaceable>]</screen>
154 <itemizedlist>
155 <listitem><para>
156 <replaceable>category</replaceable> is the resource type,
157 such as <literal>CPU</literal>, <literal>RAM</literal>,
158 <literal>FS</literal>, <literal>Net</literal>.
159 </para></listitem>
160 <listitem><para>
161 <replaceable>metric</replaceable> is a measurement type that
162 is associated with the resource category. For example, the
163 <literal>Load</literal> and <literal>MHz</literal> metrics
164 are associated with the <literal>CPU</literal> resource
165 category.
166 </para></listitem>
167 <listitem><para>
168 <replaceable>submetric</replaceable> is an optional
169 measurement type that is associated with the metric. For
170 example, the <literal>User</literal>,
171 <literal>Kernel</literal>, and <literal>Idle</literal>
172 submetrics are associated with the <literal>Load</literal>
173 metric.
174 </para></listitem>
175 <listitem><para>
176 <replaceable>sub-submetric</replaceable> is an optional
177 measurement type that is associated with the submetric. For
178 example, the <literal>Rx</literal> and <literal>Tx</literal>
179 sub-submetrics are associated with the
180 <literal>Rate</literal> submetric of the
181 <literal>Net</literal> resource category. The associated
182 metric is the network interface.
183 </para></listitem>
184 <listitem><para>
185 <replaceable>aggregate</replaceable> is an optional function
186 to provide minimum, maximum, and average measurements for a
187 resource category. For example, the
188 <literal>RAM/Usage/Free:min</literal> metric represents the
189 minimum amount of available memory found in all saved data
190 on the host system.
191 </para></listitem>
192 </itemizedlist>
193 <para>
194 By default, the <command>VBoxManage metrics</command> commands
195 operate on the host system and all VMs, and report on all
196 metrics. You can optionally limit these commands to operate on
197 the host system or on a particular VM, and report on a list of
198 one or more metrics.
199 </para>
200 </refsect2>
201 <refsect2 id="vboxmanage-metrics-common-options">
202 <title>Common Options</title>
203 <variablelist>
204 <varlistentry>
205 <term><literal>*</literal> | <literal>host</literal> | <replaceable>vmname</replaceable></term>
206 <listitem><para>
207 Specifies the component on which to operate. By default,
208 this command operates on the host system and all running
209 VMs.
210 </para><para>
211 If you specify <literal>host</literal>, the
212 <command>VBoxManage metrics</command> command operates on
213 the host system only. If you specify an asterisk
214 (<literal>*</literal>), the command operates on all VMs.
215 If you specify the name of a VM, the <command>VBoxManage
216 metrics</command> command operates on that VM.
217 </para></listitem>
218 </varlistentry>
219 <varlistentry>
220 <term><replaceable>metric-list</replaceable></term>
221 <listitem><para>
222 Specifies a comma-separated list of one or more metrics.
223 </para><para>
224 The form of the metric must include the
225 <replaceable>category</replaceable> and
226 <replaceable>metric</replaceable> part of the metric
227 string separated by a slash.
228 </para><para>
229 Note that the <command>VBoxManage metrics enable</command>
230 and <command>VBoxManage metrics disable</command> commands
231 require that you specify metrics as parameters. The
232 metrics must include only the resource category and metric
233 part, such as <literal>CPU/Load</literal> and
234 <literal>RAM/Usage</literal>.
235 </para></listitem>
236 </varlistentry>
237 </variablelist>
238 </refsect2>
239 <refsect2 id="vboxmanage-metrics-collect">
240 <title>Collect Data Metrics</title>
241 <remark role="help-copy-synopsis"/>
242 <para>
243 The <command>VBoxManage metrics collect</command> command
244 collects and outputs data periodically until you stop the
245 process by pressing Ctrl+C.
246 </para>
247 <variablelist>
248 <varlistentry>
249 <term><option>--detach</option></term>
250 <listitem><para>
251 Disables the collection of metric data, so no data is
252 output. Using this option is the same as running the
253 <command>VBoxManage metrics setup</command> command.
254 </para></listitem>
255 </varlistentry>
256 <varlistentry>
257 <term><option>--list</option></term>
258 <listitem><para>
259 Shows which metrics match the specified filter.
260 </para></listitem>
261 </varlistentry>
262 <varlistentry>
263 <term><option>--period=<replaceable>seconds</replaceable></option></term>
264 <listitem><para>
265 Specifies the number of seconds to wait between collecting
266 metric data samples. The default value is 1.
267 </para></listitem>
268 </varlistentry>
269 <varlistentry>
270 <term><option>--samples=<replaceable>count</replaceable></option></term>
271 <listitem><para>
272 Specifies the number of metric data samples to save. To
273 view the saved data, use the <command>VBoxManage metrics
274 query</command> command. The default value is 1.
275 </para></listitem>
276 </varlistentry>
277 </variablelist>
278 </refsect2>
279 <refsect2 id="vboxmanage-metrics-disable">
280 <title>Disable Metric Data Collection</title>
281 <remark role="help-copy-synopsis"/>
282 <para>
283 The <command>VBoxManage metrics disable</command> command
284 suspends data collection. This action does not affect the data
285 collection properties or the collected data. Note that
286 specifying a submetric in the metric list does not disable its
287 underlying metrics.
288 </para>
289 <para>
290 Note that the <command>VBoxManage metrics disable</command>
291 command requires that you specify metrics as parameters. The
292 metrics must include only the resource category and metric part,
293 such as <literal>CPU/Load</literal> and
294 <literal>RAM/Usage</literal>.
295 </para>
296 <variablelist>
297 <varlistentry>
298 <term><option>--list</option></term>
299 <listitem><para>
300 Shows whether the command succeeded as expected.
301 </para></listitem>
302 </varlistentry>
303 </variablelist>
304 </refsect2>
305 <refsect2 id="vboxmanage-metrics-enable">
306 <title>Enable Metric Data Collection</title>
307 <remark role="help-copy-synopsis"/>
308 <para>
309 The <command>VBoxManage metrics enable</command> command resumes
310 data collection after it has been suspended by using the
311 <command>VBoxManage metrics disable</command> command. Note that
312 specifying a submetric in the metric list does not enable its
313 underlying metrics.
314 </para>
315 <para>
316 Unlike the <command>VBoxManage metrics setup</command> command,
317 the <command>VBoxManage metrics enable</command> command does
318 not discard previously collected samples for the specified set
319 of objects and metrics.
320 </para>
321 <para>
322 Note that the <command>VBoxManage metrics enable</command>
323 command requires that you specify metrics as parameters. The
324 metrics must include only the resource category and metric part,
325 such as <literal>CPU/Load</literal> and
326 <literal>RAM/Usage</literal>.
327 </para>
328 <variablelist>
329 <varlistentry>
330 <term><option>--list</option></term>
331 <listitem><para>
332 Shows whether the command succeeded as expected.
333 </para></listitem>
334 </varlistentry>
335 </variablelist>
336 </refsect2>
337 <refsect2 id="vboxmanage-metrics-list">
338 <title>List Metric Values</title>
339 <remark role="help-copy-synopsis"/>
340 <para>
341 The <command>VBoxManage metrics list</command> command shows the
342 metrics that are currently available. Note that VM-specific
343 metrics are shown only when that VM is running.
344 </para>
345 </refsect2>
346 <refsect2 id="vboxmanage-metrics-query">
347 <title>List Saved Metric Data</title>
348 <remark role="help-copy-synopsis"/>
349 <para>
350 The <command>VBoxManage metrics query</command> command
351 retrieves and shows the saved metric data.
352 </para>
353 <para>
354 Note that the <command>VBoxManage metrics query</command>
355 command does not remove or flush saved data but older samples
356 are replaced by newer samples over time.
357 </para>
358 </refsect2>
359 <refsect2 id="vboxmanage-metrics-setup">
360 <title>Configure Metric-Gathering Properties</title>
361 <remark role="help-copy-synopsis"/>
362 <para>
363 The <command>VBoxManage metrics setup</command> command
364 configures metric-gathering properties.
365 </para>
366 <para>
367 Note that this command discards any previously collected samples
368 for the specified set of objects and metrics. To enable or
369 disable metrics collection without discarding the data, use the
370 <command>VBoxManage metrics enable</command> command or the
371 <command>VBoxManage metrics disable</command> command,
372 respectively.
373 </para>
374 <variablelist>
375 <varlistentry>
376 <term><option>--list</option></term>
377 <listitem><para>
378 Shows which metrics have been modified as a result of the
379 command execution.
380 </para></listitem>
381 </varlistentry>
382 <varlistentry>
383 <term><option>--period=<replaceable>seconds</replaceable></option></term>
384 <listitem><para>
385 Specifies the number of seconds to wait between collecting
386 metric data samples. The default value is 1.
387 </para></listitem>
388 </varlistentry>
389 <varlistentry>
390 <term><option>--samples=<replaceable>count</replaceable></option></term>
391 <listitem><para>
392 Specifies the number of metric data samples to save. To
393 view the saved data, use the <command>VBoxManage metrics
394 query</command> command. The default value is 1.
395 </para></listitem>
396 </varlistentry>
397 </variablelist>
398 </refsect2>
399 </refsect1>
400
401 <refsect1 id="vboxmanage-metrics-examples">
402 <title>Examples</title>
403 <remark role="help-scope" condition="GLOBAL"/>
404 <para>
405 The following example command enables the collection of host
406 processor and memory usage metrics every second. The
407 <option>--samples</option> option saves the five latest samples.
408 </para>
409<screen>$ VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen>
410 <para>
411 The following command lists the metrics that are available to the
412 host system and VMs:
413 </para>
414<screen>$ VBoxManage metrics list</screen>
415 <para>
416 Note that the host system and VMs have different sets of metrics.
417 </para>
418 <para>
419 The following example shows how to query metric data about the CPU
420 time spent in user and kernel modes for the
421 <literal>test</literal> VM:
422 </para>
423<screen>$ VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen>
424 </refsect1>
425</refentry>
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette