1VHOSTMD(8)                  System Manager's Manual                 VHOSTMD(8)
2
3
4

NAME

6       vhostmd - A metrics gathering daemon.
7

SYNOPSIS

9       vhostmd [ OPTION ]
10

DESCRIPTION

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
19       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

OPTIONS

26       -h, --help
27              Display help and exit
28
29       -v, --verbose
30              Verbose messages
31
32       -d, --no-daemonize
33              Process will not daemonize
34
35       -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
41       -u, --user <user>
42              Drop root privileges and run as the named non-root user.
43
44       -p, --pid-file <file>
45              Specify  an  alternate path for vhostmd to record its process-id
46              in. Normally /var/run/vhostmd.pid
47
48       -f, --config <file>
49              Specify    a    different    configuration    file.     Normally
50              /etc/vhostmd/vhostmd.conf
51

CONFIG FILE

53       At startup, vhostmd reads /etc/vhostmd/vhostmd.conf, if it exists.
54        (See the -f option.)
55
56       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
61         <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
133       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
140       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
145       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
154       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
159       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
166        virsh -r CONNECT command ...
167
168       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
173       If  the  metric  type is xml, action is expected to return valid metric
174       XML as defined below in "XML Format of Content".
175
176

Metrics Disk Format

178       Currently, the disk format is quite simple:  a  raw,  file-backed  disk
179       containing a header, immediately followed by metric content.
180
181       The header contains the following, all in network-byte order
182
183        - 4 byte signature, 'mvbd'
184        - 4 byte busy flag
185        - 4 byte content checksum
186        - 4 byte content length
187
188       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
192

XML Format of Content

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
199           <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
260

FILES

262       /etc/vhostmd/vhostmd.conf
263
264       /etc/vhostmd/vhostmd.dtd
265
266       /etc/vhostmd/metric.dtd
267
268       /var/run/vhostmd.pid
269

SEE ALSO

271
272

AUTHORS

274            Pat Campbell <plc@novell.com>.
275            Jim Fehlig <jfehlig@novell.com>.
276
277
278
279
280
281                                                                    VHOSTMD(8)
Impressum