2. Usage

This page describes how to use the exporter beyond following the quickstart guide.

2.1. Revision: Quickstart

To sign into the HMC, you have to provide credentials in the YAML format. The file hmccreds.yaml could look something like this (see also the example file shown in Sample HMC credentials file):

  userid: user
  password: password

Furthermore, the file metrics.yaml defines details about the metrics fetching. An example file is shown in Sample metric definition file, for more information on its anatomy see chapter The metrics YAML file.

Put both of these files into /etc/zhmc-prometheus-exporter (or link them). You can then run

$ zhmc_prometheus_exporter

The default port is 9291, you can change it with -p. If you do not want to put hmccreds.yaml and metrics.yaml into /etc/zhmc-prometheus-exporter, you can also specify them with -c and -m respectively.

2.2. Output anatomy

All metrics are of the Prometheus specific type Gauge. They are grouped into prefixes, e.g. dpm for general metrics read in the Dynamic Partition Manager (DPM) mode, or lpar for logical partitions in classic mode. The suffix of a metric represents the unit of measurement; for instance, a percent value will usually end with usage_ratio, while a temperature would end in celsius.

In the case of many of the metrics, they apply to multiple devices. The dpm group can have several CPCs, the partition group will usually have several partitions, etc. These devices are separated with labels, the label being resource and the value being the CPC name, the partition name, etc.

2.3. Available metrics

This is an easier to read version of the relevant parts from the HMC Web Services API Documentation. On the first level, you can read the metric groups and their prefixes. They will additionally be prefixed with zhmc_. On the second level, you can read the metrics and their exporter name without the prefix.

Only in classic mode

  • cpc-usage-overview as cpc
  • logical-partition-usage as lpar
  • channel-usage as channel

Only in DPM mode

  • dpm-system-usage-overview as dpm
    • network-usage as network_usage_ratio
    • temperature-celsius as temperature_celsius
    • storage-usage as storage_usage_ratio
    • crypto-usage as crypto_usage_ratio
    • processor-usage as processor_usage_ratio
    • accelerator-usage as accelerator_usage_ratio
    • all-shared-processor-usage as shared_processor_usage_ratio
    • power-consumption-watts as power_watts
    • ifl-shared-processor-usage as ifl_shared_processor_usage_ratio
    • ifl-all-processor-usage as ifl_total_processor_usage_ratio
    • cp-shared-processor-usage as cp_shared_usage_ratio
    • cp-all-processor-usage as cp_total_usage_ratio
  • partition-usage as partition
    • accelerator-usage as accelerator_usage_ratio
    • crypto-usage as crypto_usage_ratio
    • network-usage as network_usage_ratio
    • processor-usage as processor_usage_ratio
    • storage-usage as storage_usage_ratio
  • adapter-usage as adapter
  • crypto-usage as crypto
  • flash-memory-usage as flash
  • roce-usage as roce

Only in ensemble mode

  • virtualization-host-cpu-memory-usage as virtualized

2.4. The metrics YAML file

Various properties about scraping are collected from the metrics.yaml file that is given to the exporter with the -m option.

2.4.1. The metric groups section

contains the metric groups, as seen on the first level of the lists in Available metrics.


  prefix: dpm
  fetch: True

Within one section, the metric prefix and the fetch True/False value is stored. Note that the former will additionally be prefixed with zhmc_. The latter is due to runtime concerns: Some metric groups take over a second to be scraped.

2.4.2. The metrics section

contains the metrics themselves, as seen on the second level of the lists in Available metrics.


    percent: True
    exporter_name: network_usage_ratio
    exporter_desc: DPM total network usage

The first level section is the metric group, the second level section is the metric. Within one metric section, a percent True/False value is stored, as well as the name and description for the exporter. The former is required because for the HMC, 100% means 100, whereas for Prometheus, 100% means 1. The latter two are requirements for an exporter, the exporter_name will be prepended with the group prefix and an underscore.