---
title: Exposing downward metrics for virtual machines
---

# Exposing downward metrics for virtual machines {#virt-exposing-downward-metrics}

As an administrator, you can expose a set of host and virtual machine (VM) metrics to a guest VM by enabling the `downwardMetrics` feature gate and configuring a downward metrics device. You can view these metrics by using the command line or the `vm-dump-metrics` tool.

> [!NOTE]
> On Red Hat Enterprise Linux (RHEL) 9, use the command line to view downward metrics.
>
> The `vm-dump-metrics` tool is not supported on the Red Hat Enterprise Linux (RHEL) 9 platform.

## Enabling or disabling the downward metrics feature gate in a YAML file {#virt-enabling-disabling-downward-metrics-feature-gate-yaml_virt-exposing-downward-metrics}

To expose downward metrics for a host virtual machine, you can enable the `downwardMetrics` feature gate by editing a YAML file.

**Prerequisites**

- You must have administrator privileges to enable the feature gate.
- You have installed the OpenShift CLI (`oc`).

**Procedure**

1. Open the HyperConverged custom resource (CR) in your default editor by running the following command:

   ```terminal
   $ oc edit hyperconvergeds.v1beta1.hco.kubevirt.io kubevirt-hyperconverged -n openshift-cnv
   ```
2. Choose to enable or disable the downwardMetrics feature gate as follows:

   - To enable the `downwardMetrics` feature gate, add and then set `spec.featureGates.downwardMetrics` to `true`. For example:

     ```yaml
     apiVersion: hco.kubevirt.io/v1beta1
     kind: HyperConverged
     metadata:
       name: kubevirt-hyperconverged
       namespace: openshift-cnv
     spec:
         featureGates:
           downwardMetrics: true
     # ...
     ```
   - To disable the `downwardMetrics` feature gate, set `spec.featureGates.downwardMetrics` to `false`. For example:

     ```yaml
     apiVersion: hco.kubevirt.io/v1beta1
     kind: HyperConverged
     metadata:
       name: kubevirt-hyperconverged
       namespace: openshift-cnv
     spec:
         featureGates:
           downwardMetrics: false
     # ...
     ```

## Enabling or disabling the downward metrics feature gate from the CLI {#virt-enabling-disabling-downward-metrics-feature-gate-cli_virt-exposing-downward-metrics}

To expose downward metrics for a host virtual machine, you can enable the `downwardMetrics` feature gate by using the command line.

**Prerequisites**

- You must have administrator privileges to enable the feature gate.
- You have installed the OpenShift CLI (`oc`).

**Procedure**

- Choose to enable or disable the `downwardMetrics` feature gate as follows:

  - Enable the `downwardMetrics` feature gate by running the command shown in the following example:

    ```terminal
    $ oc patch hyperconvergeds.v1beta1.hco.kubevirt.io kubevirt-hyperconverged -n openshift-cnv \
      --type json -p '[{"op": "replace", "path": \
      "/spec/featureGates/downwardMetrics", \
      "value": true}]'
    ```
  - Disable the `downwardMetrics` feature gate by running the command shown in the following example:

    ```terminal
    $ oc patch hyperconvergeds.v1beta1.hco.kubevirt.io kubevirt-hyperconverged -n openshift-cnv \
      --type json -p '[{"op": "replace", "path": \
      "/spec/featureGates/downwardMetrics", \
      "value": false}]'
    ```

## Configuring a downward metrics device {#virt-configuring-downward-metrics_virt-exposing-downward-metrics}

You can enable the capturing of downward metrics for a host VM by creating a configuration file that includes a `downwardMetrics` device. Adding this device establishes that the metrics are exposed through a `virtio-serial` port.

**Prerequisites**

- You must first enable the `downwardMetrics` feature gate.

**Procedure**

- Edit or create a YAML file that includes a `downwardMetrics` device, as shown in the following example:

  ```yaml
  apiVersion: kubevirt.io/v1
  kind: VirtualMachine
  metadata:
    name: fedora
    namespace: default
  spec:
    dataVolumeTemplates:
      - metadata:
          name: fedora-volume
        spec:
          sourceRef:
            kind: DataSource
            name: fedora
            namespace: openshift-virtualization-os-images
          storage:
            resources: {}
    instancetype:
      name: u1.medium
    runStrategy: Always
    template:
      metadata:
        labels:
          app.kubernetes.io/name: headless
      spec:
        domain:
          devices:
            downwardMetrics: {}
        subdomain: headless
        volumes:
          - dataVolume:
              name: fedora-volume
            name: rootdisk
          - cloudInitNoCloud:
              userData: |
                #cloud-config
                chpasswd:
                  expire: false
                password: '<password>'
                user: fedora
            name: cloudinitdisk
  ```
- `spec.domain.devices.downwardMetrics` defines the `downwardMetrics` device.
- `spec.volumes.cloudInitNoCloud.userdata.password` defines the password for the `fedora` user.

## Viewing downward metrics by using the CLI {#virt-viewing-downward-metrics-cli_virt-exposing-downward-metrics}

You can view downward metrics by entering a command from inside a guest virtual machine (VM).

**Procedure**

- Run the following commands:

  ```terminal
  $ sudo sh -c 'printf "GET /metrics/XML\n\n" > /dev/virtio-ports/org.github.vhostmd.1'
  ```

  ```terminal
  $ sudo cat /dev/virtio-ports/org.github.vhostmd.1
  ```

## Viewing downward metrics by using the vm-dump-metrics tool {#virt-viewing-downward-metrics-tool_virt-exposing-downward-metrics}

To view downward metrics, install the `vm-dump-metrics` tool and then use the tool to expose the metrics results.

> [!NOTE]
> On Red Hat Enterprise Linux (RHEL) 9, use the command line to view downward metrics. The vm-dump-metrics tool is not supported on the Red Hat Enterprise Linux (RHEL) 9 platform.

**Procedure**

1. Install the `vm-dump-metrics` tool by running the following command:

   ```terminal
   $ sudo dnf install -y vm-dump-metrics
   ```
2. Retrieve the metrics results by running the following command:

   ```terminal
   $ sudo vm-dump-metrics
   ```

   Example output:

   ```xml
   <metrics>
     <metric type="string" context="host">
       <name>HostName</name>
       <value>node01</value>
   [...]
     <metric type="int64" context="host" unit="s">
       <name>Time</name>
       <value>1619008605</value>
     </metric>
     <metric type="string" context="host">
       <name>VirtualizationVendor</name>
       <value>kubevirt.io</value>
     </metric>
   </metrics>
   ```

**Additional resources**
{._additional-resources}

- [Viewing downward metrics by using the command line](/openshift-docs-markdown/virt/monitoring/virt-exposing-downward-metrics#virt-viewing-downward-metrics-cli_virt-exposing-downward-metrics)