Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
documentation.suse.com / Setting Up Virtual Host Metrics Daemon on SUSE Linux Micro

Setting Up Virtual Host Metrics Daemon on SUSE Linux Micro

Publication Date: 05 Dec 2024
WHAT?

vhostmd is a tool that collects metrics from a virtual machine host and can provide these metrics to the virtual machines running on that host.

WHY?

The article describes how to install and configure vhostmd to enable collecting metrics.

EFFORT

It takes approximately 15 minutes to read the article.

GOAL

You will have the vhostmd tool running and collecting metrics.

REQUIREMENTS

  • a running instance of SUSE Linux Micro

  • virtual machines running on that instance

1 What is a virtual host metrics daemon aka vhostmd?

 

vhostmd is a daemon that runs in a host environment and provides a metrics communication channel between the host and guest machines. The daemon provides the guest machine administrator with a limited set of host resource usage data (usually in read-only mode), to help analyze issues with the guest machine.

vhostdmd periodically writes metrics to a disk. The metrics to be collected, along with the frequency and storage location of the data, are configurable parameters.

2 Getting vhostmd

 

By default, vhostmd is not included in the delivered images. Therefore, you must install it before using it:

  1. Install the daemon by running: 

    > sudo transactional-update pkg install vhostmd

  2. Reboot your system to switch to the new snapshot.

  3. Start the daemon by running: 

    > sudo vhostmd OPTIONS

    You can use the following options to modify the command behavior:

    • -v — for a verbose output

    • --connect URI—to pass the URI of the libvirt daemon to establish connections to the daemon

    • -f FILE_PATH — to pass an alternative configuration file. For details regarding configuration, refer to Section 4, “Configuration of vhostmd”.

    • -p PID_FILE — to create an alternative PID file. The default is /var/run/vhostmd.pid.

    • -u USERNAME — to use a non-privileged user

You can also run vhostmd as systemd service: 

> sudo systemctl enable --now vhostmd
Note
Note: Service restart needed after configuration changes

Whenever you perform changes to configuration as described in Section 4, “Configuration of vhostmd”, restart the vhostmd service as follows: 

> sudo systemctl restart vhostmd

3 Providing collected metrics to a virtual machine

 

You can make the collected metrics visible to particular virtual machines for further use or just for reading. There are two ways to achieve this. You can either attach the metrics disk using the virsh command or adjust the domain configuration.

To attach the metrics disk in a read-only mode, run virsh as follows: 

> sudo virsh attach-disk VIRTUAL_MACHINE \ 
  PATH_TO_METRICS_DISC --driver tap \
  --subdriver aio --type disk --mode readonly

To change the domain configuration, proceed as follows:

  1. Run the command

    > sudo virsh edit
   GUEST_NAME

  2. Update the <devices> section by adding the following snippet: 

    <disk type='block' device='disk'>
  <source dev='/dev/shm/vhostmd0'/>
  <target dev='hdb' bus='ide'/>
  <readonly/>
</disk>

    Adjust the dev and dbus values of the target.

4 Configuration of vhostmd

 

The default configuration file of vhostmd is located in /etc/vhostmd/vhostmd.conf. You can adjust this file to suit your needs. The configuration file is an XML file that must include the <vhostmd> element. <vhostmd> then includes <globals> and <metrics> that are described in the following sections. Use the default configuration file as a reference for custom changes.

4.1 The <globals> element

 

The <globals> element defines the disk storage location, data update frequency and the method of transporting data to guest machines. It contains the following elements:

<disk>

The element is used to define the path of the disk where metrics data is stored and also the size of the disk. It may contain the following elements:

  • <name> — defines the name of the disk

  • <path> — an absolute path where the disk is mounted

  • <size> — using the unit attribute, specify the maximum size of the metrics. Use k for KB, m for MB.

<update_period>

Defines how often the metrics are updated. The value is in seconds.

<transport>

Specifies how the metrics are transported to guest machines. In the case of SUSE Linux Micro, use the default of virtio.

<virtio>

Here you can use the following elements:

  • <max_channels>—specifies the maximum number virtion can use between the host and guest systems.

  • <expiration_time>—defines the time interval after which a virtio channel of a virtual machine is closed when being idle. The default value is three times the <update_period>.

4.2 The <metrics> element

 

The <metrics> element contains a list of metrics to be collected. Each metric has two attributes:

type

Describes the metrics value data type. Possible values are the following: int32, uint32, int64, uint64, real32, real64, string, group and xml.

Use group when a metric returns several values. xml is a versatile form when the metric returns a valid XML.

context

Defines where the particular metric is collected. Possible values are:

  • host for metrics collected on the host machine

  • vm for metrics collected on the guest machine

Each metric must have a unique name and a command to run to record the metrics. The following list describes possible elements to define a metric:

<name>

Defines the unique variable name. If the metric is collected on a virtual machine, you can use the following values here: NAME, ID and UUID. Those values are then replaced with the actual ones of the virtual machine currently being checked.

<action>

Specifies a command or script to run to collect a metric. For example, to gather total CPU time, use: 

<action>virsh dominfo NAME | sed 's/: */:/' | \
    gawk -F: '/CPU time/ {print $2;}'<action>
<variable>

if an action retuns a group of values, define variables that store particular data. The element needs to have the following attributes defined:

  • name — specify the name of a variable

  • type — specify the data type of the variable

5 How are the collected metrics stored?

 

vhostmd stores the collected metrics data on the metrics disk in a raw format. The disk contains a 32-byte header followed by the metrics data in XML format.

5.1 Metrics XML format

 

The collected metrics results are similar to the configured metrics definition. The <metric> element can have the following attributes:

type

Denotes the data type of the particular metric, for example, string.

context

Identifies whether the metric is collected on the host (host) or on a virtual machine (vm).

id

Used in the vm context. Conveys the ID number of the virtual machine.

uuid

Used in the vm context. Conveys the Universally Unique Identifier of the virtual machine.

The <metric> element contains the following elements:

<name>

Conveys the metric name.

<value>

Conveys the metrics actual value.

Note
Note: No multiple values within one metric

When the group type of a metric has been configured, each configured <variable> is stored as a separate metric in the result. For example, the following configuration snippet: 

<metric type="group" context="host">
  <name>PageRates</name>
  <action>pagerate.pl</action>
  <variable name="PageInRate" type="uint64"/>
  <variable name="PageFaultRate" type="uint64"/>
</metric>

Results in the following snippet: 

<metric type='uint64' context='host'>
  <name>PageInRate</name>
  <value>0.000000</value>
</metric>
<metric type='uint64' context='host'>
  <name>PageFaultRate</name>
  <value>0.000000</value>
</metric>