.. _Enabling Metering for Compute Resources:

Enabling Metering for Compute Resources
---------------------------------------

You can collect usage data of compute resources using Gnocchi. It is a time series database that processes and stores measurement data of compute resources and provides access to it via REST API or the command-line tool.

Gnocchi aggregates and stores measures for compute resource metrics according to their archive policy. The policy defines how long aggregates are kept in a metric and how they are computed (minimum, maximum, average, etc.). The archive policy is set when a metric is created and cannot be changed afterwards. All the existing metrics have the ``low`` archive policy, meaning that all computed aggregates are kept for one day with 5-minute granularity and one month with 1-hour granularity. 

The following metrics are available for aggregation:

.. tabularcolumns:: |>{\TL}\X{1}{7}%
                    |>{\TL}\X{2}{7}%
                    |>{\TL}\X{1}{7}%
                    |>{\TL}\X{3}{7}|

.. table:: Compute resource metrics
   :class: longtable

   +-----------------+------------------------------+------------+-------------------------------------------------+
   | Resource        | Metric                       | Type       | Description                                     |
   +=================+==============================+============+=================================================+
   | Virtual machine | ``memory``                   | gauge      | Amount of RAM allocated to the VM, in megabytes |
   |                 +------------------------------+------------+-------------------------------------------------+
   |                 | ``vcpus``                    | gauge      | Number of virtual CPUs allocated to the VM      |
   |                 +------------------------------+------------+-------------------------------------------------+
   |                 | ``disk.read.requests``       | cumulative | Number of read requests                         |
   |                 +------------------------------+------------+-------------------------------------------------+
   |                 | ``disk.write.requests``      | cumulative | Number of write requests                        |
   |                 +------------------------------+------------+-------------------------------------------------+
   |                 | ``disk.read.bytes``          | cumulative | Amount of data read, in bytes                   |
   |                 +------------------------------+------------+-------------------------------------------------+
   |                 | ``disk.write.bytes``         | cumulative | Amount of data written, in bytes                |
   |                 +------------------------------+------------+-------------------------------------------------+
   |                 | ``network.incoming.bytes``   | cumulative | Incoming network traffic, in bytes              |
   |                 +------------------------------+------------+-------------------------------------------------+
   |                 | ``network.outgoing.bytes``   | cumulative | Outgoing network traffic, in bytes              |
   |                 +------------------------------+------------+-------------------------------------------------+
   |                 | ``network.incoming.packets`` | cumulative | Incoming network traffic, in packets            |
   |                 +------------------------------+------------+-------------------------------------------------+
   |                 | ``network.outgoing.packets`` | cumulative | Outgoing network traffic, in packets            |
   +-----------------+------------------------------+------------+-------------------------------------------------+
   | Image           | ``image.size``               | gauge      | Size of the uploaded image, in bytes            |
   +-----------------+------------------------------+------------+-------------------------------------------------+
   | Volume          | ``volume.size``              | gauge      | Size of the volume, in gigabytes                |
   +-----------------+------------------------------+------------+-------------------------------------------------+
   | Snapshot        | ``snapshot.size``            | gauge      | Size of the volume snapshot, in gigabytes       |
   +-----------------+------------------------------+------------+-------------------------------------------------+
   | IP address      | ``ip.floating``              | gauge      | Number of floating IP addresses                 |
   +-----------------+------------------------------+------------+-------------------------------------------------+

Cumulative metrics are polled every 5 minutes and increase over time, while gauge metrics are updated on events and show fluctuating values.

You can enable metering services in your compute cluster by doing one of the following:

- If you have no compute cluster yet, deploy it and enable metering by adding the ``--enable-metering`` option to the ``vinfra service compute cluster create`` command. For example:

  ::

     # vinfra service compute create --nodes <node1_id>[,<node2_id>,...] --enable-metering

- If you have already created the compute cluster, use the following command:

  ::

     # vinfra service compute cluster set --enable-metering

  .. note:: Gnocchi will only take into account virtual machines created after metering has been enabled.

These commands open port 8041 and enable two Gnocchi services: ``gnocchi-api``, an HTTP server, and ``gnocchi-metricd``, a metric daemon.

After enabling metering, you can get access to your compute resource metrics either via REST API (see `the official documentation <https://gnocchi.xyz/rest.html>`__) or using the Gnocchi command-line tool. To be able to use the tool, do as follows: 

#. Install the Gnocchi client:

   ::

      # yum install python-gnocchiclient

#. Generate the admin OpenRC file:

   ::

      # su - vstoradmin -c 'kolla-ansible post-deploy'
      # source /etc/kolla/admin-openrc.sh
   
Now you can use the ``gnocchi`` command with the ``--insecure`` option. For example, to get a sum of vCPUs allocated to all virtual machines in the compute cluster and group them by project, use the following command:

::

   # gnocchi --insecure measures aggregation --aggregation sum --metric vcpus \
   --groupby=project_id --query=dummy --needed-overlap=0
   +---------------------------+---------------------------+-------------+-------+
   | group                     | timestamp                 | granularity | value |
   +---------------------------+---------------------------+-------------+-------+
   | project_id: 7decddff<...> | 2019-08-13T14:00:00+03:00 |       300.0 |   2.0 |
   | project_id: 7decddff<...> | 2019-08-13T15:00:00+03:00 |       300.0 |   2.0 |
   | project_id: b5bf7f3e<...> | 2019-08-13T14:00:00+03:00 |       300.0 |   4.0 |
   | project_id: b5bf7f3e<...> | 2019-08-13T15:00:00+03:00 |       300.0 |   4.0 |
   +---------------------------+---------------------------+-------------+-------+

The output shows that at 2 and 3 p.m. on August 13, 2019 VMs included in the two projects were allocated 2 and 4 vCPUs, respectively.

To see the full list of ``gnocchi`` commands, refer to `the official documentation <https://gnocchi.xyz/gnocchiclient/shell.html#commands-descriptions>`__.