VirtualBox

Changeset 94210 in vbox for trunk/doc/manual


Ignore:
Timestamp:
Mar 13, 2022 8:25:00 PM (3 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
150466
Message:

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

Location:
trunk/doc/manual
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/manual/Config.kmk

    r94209 r94210  
    7979        man_VBoxManage-usbfilter.xml \
    8080        man_VBoxManage-guestproperty.xml \
    81         man_VBoxManage-guestcontrol.xml
     81        man_VBoxManage-guestcontrol.xml \
     82        man_VBoxManage-metrics.xml
    8283
    8384## List of user manual XML files.
  • trunk/doc/manual/en_US/man_VBoxManage-metrics.xml

    r82969 r94210  
    2020<refentry id="vboxmanage-metrics" lang="en">
    2121  <refentryinfo>
    22     <pubdate>September 2019</pubdate>
     22    <pubdate>$Date$</pubdate>
    2323    <title>VBoxManage metrics</title>
    2424  </refentryinfo>
     
    3232    <refname>VBoxManage-metrics</refname>
    3333    <refpurpose>monitor system resource usage</refpurpose>
    34     <refclass>Oracle VM VirtualBox</refclass>
     34    <refclass>&product-name;</refclass>
    3535  </refnamediv>
    3636
  • trunk/doc/manual/en_US/user_VBoxManage.xml

    r94209 r94210  
    11171117  <xi:include href="user_man_VBoxManage-debugvm.xml"        xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    11181118
    1119   <sect1 id="vboxmanage-metrics">
    1120 
    1121     <title>VBoxManage metrics</title>
    1122 
    1123     <para>
    1124       This command supports monitoring the usage of system resources.
    1125       Resources are represented by various metrics associated with the
    1126       host system or a particular VM. For example, the host system has a
    1127       <computeroutput>CPU/Load/User</computeroutput> metric that shows
    1128       the percentage of time CPUs spend executing in user mode over a
    1129       specific sampling period.
    1130     </para>
    1131 
    1132     <para>
    1133       Metric data is collected and retained internally. It may be
    1134       retrieved at any time with the <command>VBoxManage metrics
    1135       query</command> subcommand. The data is available as long as the
    1136       background <computeroutput>VBoxSVC</computeroutput> process is
    1137       alive. That process terminates shortly after all VMs and frontends
    1138       have been closed.
    1139     </para>
    1140 
    1141     <para>
    1142       By default no metrics are collected at all. Metrics collection
    1143       does not start until <command>VBoxManage metrics setup</command>
    1144       is invoked with a proper sampling interval and the number of
    1145       metrics to be retained. The interval is measured in seconds. For
    1146       example, to enable collecting the host processor and memory usage
    1147       metrics every second and keeping the five most current samples,
    1148       the following command can be used:
    1149     </para>
    1150 
    1151 <screen>VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen>
    1152 
    1153     <para>
    1154       Metric collection can only be enabled for started VMs. Collected
    1155       data and collection settings for a particular VM will disappear as
    1156       soon as it shuts down. Use the <command>VBoxManage metrics
    1157       list</command> subcommand to see which metrics are currently
    1158       available. You can also use the <option>--list</option> option
    1159       with any subcommand that modifies metric settings to find out
    1160       which metrics were affected.
    1161     </para>
    1162 
    1163     <para>
    1164       Note that the <command>VBoxManage metrics setup</command>
    1165       subcommand discards all samples that may have been previously
    1166       collected for the specified set of objects and metrics.
    1167     </para>
    1168 
    1169     <para>
    1170       To enable or disable metrics collection without discarding the
    1171       data, <command>VBoxManage metrics enable</command> and
    1172       <command>VBoxManage metrics disable</command> subcommands can be
    1173       used. Note that these subcommands expect metrics as parameters,
    1174       not submetrics such as <computeroutput>CPU/Load</computeroutput>
    1175       or <computeroutput>RAM/Usage</computeroutput>. In other words
    1176       enabling <computeroutput>CPU/Load/User</computeroutput> while
    1177       disabling <computeroutput>CPU/Load/Kernel</computeroutput> is not
    1178       supported.
    1179     </para>
    1180 
    1181     <para>
    1182       The host and VMs have different sets of associated metrics.
    1183       Available metrics can be listed with <command>VBoxManage metrics
    1184       list</command> subcommand.
    1185     </para>
    1186 
    1187     <para>
    1188       A complete metric name may include an aggregate function. The name
    1189       has the following form:
    1190       <computeroutput>Category/Metric[/SubMetric][:aggregate]</computeroutput>.
    1191       For example, <computeroutput>RAM/Usage/Free:min</computeroutput>
    1192       stands for the minimum amount of available memory over all
    1193       retained data if applied to the host object.
    1194     </para>
    1195 
    1196     <para>
    1197       Subcommands may apply to all objects and metrics or can be limited
    1198       to one object and a list of metrics. If no objects or metrics are
    1199       given in the parameters, the subcommands will apply to all
    1200       available metrics of all objects. You may use an asterisk
    1201       "<computeroutput>*</computeroutput>" to explicitly specify that
    1202       the command should be applied to all objects or metrics. Use
    1203       <computeroutput>host</computeroutput> as the object name to limit
    1204       the scope of the command to host-related metrics. To limit the
    1205       scope to a subset of metrics, use a metric list with names
    1206       separated by commas.
    1207     </para>
    1208 
    1209     <para>
    1210       For example, to query metric data on the CPU time spent in user
    1211       and kernel modes by the virtual machine named
    1212       <computeroutput>test</computeroutput>, use the following command:
    1213     </para>
    1214 
    1215 <screen>VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen>
    1216 
    1217     <para>
    1218       The following list summarizes the available subcommands:
    1219     </para>
    1220 
    1221     <variablelist>
    1222 
    1223       <varlistentry>
    1224         <term>
    1225           <computeroutput>list</computeroutput>
    1226         </term>
    1227 
    1228         <listitem>
    1229           <para>
    1230             Shows the parameters of the currently existing metrics. Note
    1231             that VM-specific metrics are only available when a
    1232             particular VM is running.
    1233           </para>
    1234         </listitem>
    1235       </varlistentry>
    1236 
    1237       <varlistentry>
    1238         <term>
    1239           <computeroutput>setup</computeroutput>
    1240         </term>
    1241 
    1242         <listitem>
    1243           <para>
    1244             Sets the interval between taking two samples of metric data
    1245             and the number of samples retained internally. The retained
    1246             data is available for displaying with the
    1247             <command>query</command> subcommand. The
    1248             <computeroutput>--list</computeroutput> option shows which
    1249             metrics have been modified as the result of the command
    1250             execution.
    1251           </para>
    1252         </listitem>
    1253       </varlistentry>
    1254 
    1255       <varlistentry>
    1256         <term>
    1257           <computeroutput>enable</computeroutput>
    1258         </term>
    1259 
    1260         <listitem>
    1261           <para>
    1262             Resumes data collection after it has been stopped with the
    1263             <command>disable</command> subcommand. Note that specifying
    1264             submetrics as parameters will not enable underlying metrics.
    1265             Use <computeroutput>--list</computeroutput> to find out if
    1266             the command worked as expected.
    1267           </para>
    1268         </listitem>
    1269       </varlistentry>
    1270 
    1271       <varlistentry>
    1272         <term>
    1273           <computeroutput>disable</computeroutput>
    1274         </term>
    1275 
    1276         <listitem>
    1277           <para>
    1278             Suspends data collection without affecting collection
    1279             parameters or collected data. Note that specifying
    1280             submetrics as parameters will not disable underlying
    1281             metrics. Use <computeroutput>--list</computeroutput> to find
    1282             out if the command worked as expected.
    1283           </para>
    1284         </listitem>
    1285       </varlistentry>
    1286 
    1287       <varlistentry>
    1288         <term>
    1289           <computeroutput>query</computeroutput>
    1290         </term>
    1291 
    1292         <listitem>
    1293           <para>
    1294             Retrieves and displays the currently retained metric data.
    1295           </para>
    1296 
    1297           <note>
    1298             <para>
    1299               The <command>query</command> subcommand does not remove or
    1300               flush retained data. If you query often enough you will
    1301               see how old samples are gradually being phased out by new
    1302               samples.
    1303             </para>
    1304           </note>
    1305         </listitem>
    1306       </varlistentry>
    1307 
    1308       <varlistentry>
    1309         <term>
    1310           <computeroutput>collect</computeroutput>
    1311         </term>
    1312 
    1313         <listitem>
    1314           <para>
    1315             Sets the interval between taking two samples of metric data
    1316             and the number of samples retained internally. The collected
    1317             data is displayed periodically until Ctrl+C is pressed,
    1318             unless the <computeroutput>--detach</computeroutput> option
    1319             is specified. With the
    1320             <computeroutput>--detach</computeroutput> option, this
    1321             subcommand operates the same way as
    1322             <computeroutput>setup</computeroutput> does. The
    1323             <computeroutput>--list</computeroutput> option shows which
    1324             metrics match the specified filter.
    1325           </para>
    1326         </listitem>
    1327       </varlistentry>
    1328 
    1329     </variablelist>
    1330 
    1331   </sect1>
     1119  <xi:include href="user_man_VBoxManage-metrics.xml"        xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    13321120
    13331121  <sect1 id="vboxmanage-natnetwork">
Note: See TracChangeset for help on using the changeset viewer.

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