1VHOSTMD(8) System Manager's Manual VHOSTMD(8)
2
6 vhostmd - A metrics gathering daemon.
7
9 vhostmd [ OPTION ]
10
12 vhostmd provides a "metrics communication channel" between a host and
13 its hosted virtual machines, allowing limited introspection of host
14 resource usage from within virtual machines. This functionality may be
15 useful in hosting environments, giving virtual machine administrators a
16 limited view of host resource consumption - potentially explaining a
17 performance degradation within the virtual machine.
18 vhostmd will periodically write metrics to a disk. The metrics to
20 write, how often, and where to write them are all adjustable via the
21 /etc/vhostmd/vhostmd.conf configuration file. The disk can then be
22 surfaced read-only to virtual machines using tools provided by the
23 host's virtualization platform.
24
26 -h, --help
27 Display help and exit
28 -v, --verbose
30 Verbose messages
31 -d, --no-daemonize
33 Process will not daemonize
34 -c, --connect <uri>
36 Set the libvirt URI. If unspecified then we connect to the
37 default libvirt hypervisor. It is recommended that you specify
38 this since libvirt's method for choosing the default hypervisor
39 can give unexpected results.
40 -u, --user <user>
42 Drop root privileges and run as the named non-root user.
43 -p, --pid-file <file>
45 Specify an alternate path for vhostmd to record its process-id
46 in. Normally /var/run/vhostmd.pid
47 -f, --config <file>
49 Specify a different configuration file. Normally
50 /etc/vhostmd/vhostmd.conf
51
53 At startup, vhostmd reads /etc/vhostmd/vhostmd.conf, if it exists.
54 (See the -f option.)
55 The default configuration file (listed below) defines a 256Kbyte met‐
57 rics disk in /dev/shm/vhostmd0, updated every 5 seconds. It also
58 includes a few examples of user-defined metrics, which provide a (cur‐
59 rently simplistic) mechanism for extending metrics gathered by vhostmd.
60 <vhostmd>
62 <globals>
63 <disk>
64 <name>host-metrics-disk</name>
65 <path>/dev/shm/vhostmd0</path>
66 <size unit="k">256</size>
67 </disk>
68 <update_period>5</update_period>
69 <path>/usr/bin:/usr/sbin:/usr/share/vhostmd/scripts</path>
70 </globals>
71 <metrics>
72 <metric type="string" context="host">
73 <name>HostName</name>
74 <action>virsh hostname | tr -d '[:space:]'</action>
75 </metric>
76 <metric type="string" context="host">
77 <name>VirtualizationVendor</name>
78 <action>/bin/rpm -q --info xen | grep Vendor: |
79 awk '{print substr($0, index($0,$5)) }'</action>
80 </metric>
81 <metric type="uint32" context="host">
82 <name>TotalPhyCPUs</name>
83 <action>xm info | gawk '/^nr_cpus/ {print $3}'</action>
84 </metric>
85 <metric type="uint32" context="host">
86 <name>NumCPUs</name>
87 <action>xm info | gawk '/^nr_cpus/ {print $3}'</action>
88 </metric>
89 <metric type="uint64" context="host">
90 <name>TotalPhyMem</name>
91 <action>xm info | gawk '/^total_memory/ {print $3}'</action>
92 </metric>
93 <metric type="uint64" context="host">
94 <name>UsedMem</name>
95 <action>xentop -b -i 1 | gawk '/Domain-0/ {print $5}'</action>
96 </metric>
97 <metric type="uint64" context="host">
98 <name>FreeMem</name>
99 <action>xm info | gawk '/^max_free_memory/ {print $3}'</action>
100 </metric>
101 <metric type="uint64" context="host">
102 <name>PagedInMemory</name>
103 <action>vmstat -s | gawk '/pages paged in/ {print $1}'</action>
104 </metric>
105 <metric type="uint64" context="host">
106 <name>PagedOutMemory</name>
107 <action>vmstat -s | gawk '/pages paged out/ {print
108 $1}'</action>
109 </metric>
110 <metric type="group" context="host">
111 <name>PageRates</name>
112 <action>pagerate.pl</action>
113 <variable name="PageInRate" type="uint64"/>
114 <variable name="PageFaultRate" type="uint64"/>
115 </metric>
116 <metric type="real64" context="host">
117 <name>TotalCPUTime</name>
118 <action>virsh dominfo 0 | sed 's/: */:/' |
119 gawk -F: '/CPU time/ {print $2;}'</action>
120 </metric>
121 <metric type="real64" context="vm">
122 <name>TotalCPUTime</name>
123 <action>virsh dominfo NAME | sed 's/: */:/' |
124 gawk -F: '/CPU time/ {print $2;}'</action>
125 </metric>
126 <metric type="xml" context="vm">
127 <name>my-metric</name>
128 <action>xml-metrics-test.sh</action>
129 </metric>
130 </metrics>
131 </vhostmd>
132 A valid configuration file must contain the root element <vhostmd>.
134 The <globals> element contains configuration global to vhostmd, such as
135 the metrics disk path and the metrics refresh interval. The <metrics>
136 element is a container for all of the <metric> elements. A metric ele‐
137 ment is used to define a metric, giving it a name and an action that
138 produces the metric value.
139 The supplied vhostmd configuration file provides a useful set of
141 default metrics to be collected. This can be extended or modified by
142 editing /etc/vhostmd/vhostmd.conf and changing existing metric defini‐
143 tions or adding new metric definitions under the metrics container.
144 Defined metrics begin with the <metric> element, which contains two
146 attributes: type and context. The type attribute is used to describe
147 the metric's value type. Supported types are int32, uint32, int64,
148 uint64, real32, real64, string, group, and xml. group is used when an
149 action returns more than one metric value. xml is the most flexible
150 type and specifies that the metric's action returns valid metric XML.
151 The context attribute is used to indicate whether this is a host or vm
152 metric. Supported contexts are host and vm.
153 Currently, the metric element contains 3 elements: name, action, and
155 variable. The name element defines the metric's name. The action ele‐
156 ment describes a command or pipeline of commands used to gather the
157 metric.
158 Any <action> element can contain the magic token CONNECT which is
160 replaced with the string "--connect 'uri'" where uri is the libvirt
161 connection URI (specified on the command line to vhostmd as the -c
162 option). If it wasn't specified, then the token CONNECT is substituted
163 with the empty string. This allows you to write virsh commands like
164 this:
165 virsh -r CONNECT command ...
167 For metrics of vm context, the tokens NAME, VMID, and UUID may be used
169 where these attributes of a VM are normally provided in a command.
170 When the metric is sampled, these tokens will be substituted with the
171 actual name, ID, or UUID of the vm currently being sampled by vhostmd.
172 If the metric type is xml, action is expected to return valid metric
174 XML as defined below in "XML Format of Content".
175
178 Currently, the disk format is quite simple: a raw, file-backed disk
179 containing a header, immediately followed by metric content.
180 The header contains the following, all in network-byte order
182 - 4 byte signature, 'mvbd'
184 - 4 byte busy flag
185 - 4 byte content checksum
186 - 4 byte content length
187 The busy flag permits simple reader/writer synchronization. The busy
189 flag can be checked for clear, content read into a buffer, and the busy
190 flag checked again for clear to ensure stable content.
191
194 The content is an XML document containing default and user-defined met‐
195 rics. The format is quite similar to the metrics definitions found in
196 the vhostmd configuration file. A notable addition, as illustrated
197 below, is the value element containing the metric's current value.
198 <metrics>
200 <metric type='real64' context='host'>
201 <name>TotalCPUTime</name>
202 <value>846.600000</value>
203 </metric>
204 <metric type='uint64' context='host'>
205 <name>PageInRate</name>
206 <value>0.000000</value>
207 </metric>
208 <metric type='uint64' context='host'>
209 <name>PageFaultRate</name>
210 <value>0.000000</value>
211 </metric>
212 <metric type='uint64' context='host'>
213 <name>PagedOutMemory</name>
214 <value>6885044</value>
215 </metric>
216 <metric type='uint64' context='host'>
217 <name>PagedInMemory</name>
218 <value>2367980</value>
219 </metric>
220 <metric type='uint64' context='host'>
221 <name>FreeMem</name>
222 <value>829</value>
223 </metric>
224 <metric type='uint64' context='host'>
225 <name>UsedMem</name>
226 <value>1369088</value>
227 </metric>
228 <metric type='uint64' context='host'>
229 <name>TotalPhyMem</name>
230 <value>1919</value>
231 </metric>
232 <metric type='uint32' context='host'>
233 <name>NumCPUs</name>
234 <value>2</value>
235 </metric>
236 <metric type='uint32' context='host'>
237 <name>TotalPhyCPUs</name>
238 <value>2</value>
239 </metric>
240 <metric type='string' context='host'>
241 <name>VirtualizationVendor</name>
242 <value>SUSE LINUX Products GmbH</value>
243 </metric>
244 <metric type='string' context='host'>
245 <name>HostName</name>
246 <value>laptop</value>
247 </metric>
248 <metric type='real64' context='vm' id='0'
249 uuid='00000000-0000-0000-0000-000000000000'>
250 <name>TotalCPUTime</name>
251 <value>847.700000</value>
252 </metric>
253 <metric type='real64' context='vm' id='2'
254 uuid='6be3fdb8-bef5-6fec-b1b7-e61bbceab708'>
255 <name>TotalCPUTime</name>
256 <value>69.400000</value>
257 </metric>
258 </metrics>
259
262 /etc/vhostmd/vhostmd.conf
263 /etc/vhostmd/vhostmd.dtd
265 /etc/vhostmd/metric.dtd
267 /var/run/vhostmd.pid
269
271
274 Pat Campbell <plc@novell.com>.
275 Jim Fehlig <jfehlig@novell.com>.
276 VHOSTMD(8)