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