..
    Warning: Do not edit this file. It is automatically generated from the
    software project's code and your changes will be overwritten.

    The tool to generate this file lives in openstack-doc-tools repository.

    Please make any changes needed in the code, then run the
    autogenerate-config-doc tool from the openstack-doc-tools repository, or
    ask for help on the documentation mailing list, IRC channel or meeting.

.. _nova-metrics:

.. list-table:: Description of metrics configuration options
   :header-rows: 1
   :class: config-ref-table

   * - Configuration option = Default value
     - Description

   * - ``required`` = ``True``

     - (Boolean) This setting determines how any unavailable metrics are treated. If this option is set to True, any hosts for which a metric is unavailable will raise an exception, so it is recommended to also use the MetricFilter to filter out those hosts before weighing.

       This option is only used by the FilterScheduler and its subclasses; if you use a different scheduler, this option has no effect.

       Possible values:

       * True or False, where False ensures any metric being unavailable for a host will set the host weight to 'weight_of_unavailable'.

       Related options:

       * weight_of_unavailable

   * - ``weight_multiplier`` = ``1.0``

     - (Floating point) When using metrics to weight the suitability of a host, you can use this option to change how the calculated weight influences the weight assigned to a host as follows:

       * >1.0: increases the effect of the metric on overall weight

       * 1.0: no change to the calculated weight

       * >0.0,<1.0: reduces the effect of the metric on overall weight

       * 0.0: the metric value is ignored, and the value of the 'weight_of_unavailable' option is returned instead

       * >-1.0,<0.0: the effect is reduced and reversed

       * -1.0: the effect is reversed

       * <-1.0: the effect is increased proportionally and reversed

       This option is only used by the FilterScheduler and its subclasses; if you use a different scheduler, this option has no effect.

       Possible values:

       * An integer or float value, where the value corresponds to the multipler ratio for this weigher.

       Related options:

       * weight_of_unavailable

   * - ``weight_of_unavailable`` = ``-10000.0``

     - (Floating point) When any of the following conditions are met, this value will be used in place of any actual metric value:

       * One of the metrics named in 'weight_setting' is not available for a host, and the value of 'required' is False

       * The ratio specified for a metric in 'weight_setting' is 0

       * The 'weight_multiplier' option is set to 0

       This option is only used by the FilterScheduler and its subclasses; if you use a different scheduler, this option has no effect.

       Possible values:

       * An integer or float value, where the value corresponds to the multipler ratio for this weigher.

       Related options:

       * weight_setting

       * required

       * weight_multiplier

   * - ``weight_setting`` =

     - (List) This setting specifies the metrics to be weighed and the relative ratios for each metric. This should be a single string value, consisting of a series of one or more 'name=ratio' pairs, separated by commas, where 'name' is the name of the metric to be weighed, and 'ratio' is the relative weight for that metric.

       Note that if the ratio is set to 0, the metric value is ignored, and instead the weight will be set to the value of the 'weight_of_unavailable' option.

       As an example, let's consider the case where this option is set to:

        ``name1=1.0, name2=-1.3``

       The final weight will be:

        ``(name1.value * 1.0) + (name2.value * -1.3)``

       This option is only used by the FilterScheduler and its subclasses; if you use a different scheduler, this option has no effect.

       Possible values:

       * A list of zero or more key/value pairs separated by commas, where the key is a string representing the name of a metric and the value is a numeric weight for that metric. If any value is set to 0, the value is ignored and the weight will be set to the value of the 'weight_of_unavailable' option.

       Related options:

       * weight_of_unavailable