VirtualBox

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

Last change on this file since 94480 was 94210, checked in by vboxsync, 3 years ago

doc/manual,FE/VBoxManage: Convert metrics command to refentry documentation, ​bugref:9186

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