Changeset 94210 in vbox for trunk/doc/manual
- Timestamp:
- Mar 13, 2022 8:25:00 PM (3 years ago)
- svn:sync-xref-src-repo-rev:
- 150466
- Location:
- trunk/doc/manual
- Files:
-
- 3 edited
-
Config.kmk (modified) (1 diff)
-
en_US/man_VBoxManage-metrics.xml (modified) (2 diffs)
-
en_US/user_VBoxManage.xml (modified) (1 diff)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/manual/Config.kmk
r94209 r94210 79 79 man_VBoxManage-usbfilter.xml \ 80 80 man_VBoxManage-guestproperty.xml \ 81 man_VBoxManage-guestcontrol.xml 81 man_VBoxManage-guestcontrol.xml \ 82 man_VBoxManage-metrics.xml 82 83 83 84 ## List of user manual XML files. -
trunk/doc/manual/en_US/man_VBoxManage-metrics.xml
r82969 r94210 20 20 <refentry id="vboxmanage-metrics" lang="en"> 21 21 <refentryinfo> 22 <pubdate> September 2019</pubdate>22 <pubdate>$Date$</pubdate> 23 23 <title>VBoxManage metrics</title> 24 24 </refentryinfo> … … 32 32 <refname>VBoxManage-metrics</refname> 33 33 <refpurpose>monitor system resource usage</refpurpose> 34 <refclass> Oracle VM VirtualBox</refclass>34 <refclass>&product-name;</refclass> 35 35 </refnamediv> 36 36 -
trunk/doc/manual/en_US/user_VBoxManage.xml
r94209 r94210 1117 1117 <xi:include href="user_man_VBoxManage-debugvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> 1118 1118 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" /> 1332 1120 1333 1121 <sect1 id="vboxmanage-natnetwork">
Note:
See TracChangeset
for help on using the changeset viewer.
