ironic/doc/source/contributor/metrics.rst

Metrics

Ironic provides a pluggable metrics library as of the 2.0.0 release. The metrics backend to be used is configured via CONF.metrics.backend. Not all backends support all metrics types or metric sources.

The typical usage of metrics is to initialize and cache a metrics logger, using the get_metrics_logger() method in metrics_utils, then use that object to decorate functions or create context managers to gather metrics. The general convention is to provide the name of the module as the first argument to set it as the prefix, then set the actual metric name to the method name. For example:

from ironic import metrics_utils

METRICS = metrics_utils.get_metrics_logger(__name__)

@METRICS.timer('my_simple_method')
def my_simple_method(arg, matey):
    pass

def my_complex_method(arg, matey):
    with METRICS.timer('complex_method_pt_1'):
        do_some_work()

    with METRICS.timer('complex_method_pt_2'):
        do_more_work()

There are three different kinds of metrics:

• Timers measure how long the code in the decorated method or context manager takes to execute, and emits the value as a timer metric. These are useful for measuring performance of a given block of code.
• Counters increment a counter each time a decorated method or context manager is executed. These are useful for counting the number of times a method is called, or the number of times an event occurs.
• Gauges return the value of a decorated method as a metric. This is useful when you want to monitor the value returned by a method over time.

Additionally, metrics can be sent directly, rather than using a context manager or decorator, when appropriate. When used in this way, we will simply emit the value provided as the requested metric type. For example:

from ironic import metrics_utils

METRICS = metrics_utils.get_metrics_logger(__name__)

def my_node_failure_method(node):
    if node.failed:
        METRICS.send_counter(node.uuid, 1)

The provided statsd backend natively supports all three metric types. For more information about how statsd changes behavior based on the metric type, see statsd metric types