.. _configuration:

Configuration
=============

Measurement Cycle Time
----------------------

Performance counters are measured periodically.
Therefore the first aspect to decide is the :term:`measurement cycle time`.
This is the time between two consecutive measurements.
It defines the resolution of available data but also the required storage space of the timeseries database backend as well as the computational load generated by the monitoring infrastructure.
Additionally, too short cycle times will not increase the effective resolutions because several performance counters are only updated infrequently by the Linux kernel.
Therefore recommended values could be 5 or 10 seconds.

Configuration of the Timeseries Backend
---------------------------------------

InfluxDB
^^^^^^^^

Configure InfluxDB as desired using the example config files and the instructions found here in the `installation instructions <https://influxdb.com/docs/v0.8/introduction/installation.html>`_.
An exemplary config file which uses just a local computer and :file:`/tmp` for data can be :download:`downloaded <./config-files/influx-config.toml>`.
Please note that in this file the ``assets`` line in the ``admin`` section needs to be fixed so that it point to the installation of the required files for the admin web interface.
After adapting the file, start the database server, e.g. using

.. code-block:: bash

   $prefix/opt/influxdb/influxdb -config=path/to/influxdb-config.toml

Using the web interface (http://localhost:8083 per default), create a database for the monitoring data.
The retention for the proposed default shard space should be set to the desired time you plan to keep data available in the database (e.g. ``7d``).
Duration should probably be set to ``1d``.

Graphite
^^^^^^^^

Unfortunately, Graphite configuration is a bit harder than for InfluxDB.
Basically, you need to follow `these instructions <https://graphite.readthedocs.org/en/latest/install.html#initial-configuration>`_.
The steps are:

#. Configure the carbon daemon, which accepts new data via HTTP and pushes them into the timeseries database.

      #. Create a :file:`carbon.conf` file and adapt as required.
         The comments about all data directories descending from ``STORAGE_DIR`` are misleading.
         This is only true for the defaults.
         In case you want to move your data, you need to set all of these directories explicitly.
         An exemplary configuration file can be :download:`downloaded <./config-files/carbon.conf>`.
         The file needs to be placed in the :file:`conf` directory of your Graphite installation root.

      #. Create a :file:`storage-schemas.conf` file which defines the retention policies.
         The highest resolution must match the chosen :term:`measurement cycle time`. Otherwise you will end up with ``null`` values in the database.
         An examplary file can be :download:`downloaded <./config-files/storage-schemas.conf>`.
         The file needs to be placed in the `conf` directory of your Graphite installation root.

#. Configure the web application

   #. Create a :file:`local_settings.py` according to the example file.
      The `STORAGE_DIR`` variable needs to match the value that has been used for carbon.
      Otherwise, the webapp won't find the database.
      An example can be :download:`downloaded <./config-files/local_settings.py>`.
      This file needs to be placed in the :file:`webapp/graphite` directory of your installation.
      In case you do not want to set up a custom webserver, it is important to set ``DEBUG = True``.

   #. Collect static webapp files to be served by the wbeserver:

      .. code-block:: bash

         export PYTHONPATH=$GRAPHITE_ROOT/webapp:$PYTHONPATH
         django-admin.py collectstatic --noinput --settings=graphite.settings

   #. Create a configuration database for django:

      .. code-block:: bash

         PYTHONPATH=$GRAPHITE_ROOT/webapp django-admin.py syncdb --settings=graphite.settings

.. _configuration-grafana:

Configuration of the Grafana Dashboards
---------------------------------------

Create an ini file to configure the Grafana server.
An exemplary file can be :download:`downloaded <./config-files/grafana-config.ini>`.
You can place this file anywhere.

Initial Online Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In addition to providing a config file, Grafana dashboards need to be configured once the Grafana server is running.
For this purpose, first start the monitoring components as described at :doc:`startup`.
Afterwards, follow these steps once:

#. Clone the dashboard repository to your local computer:

   .. code-block:: bash

      git clone https://code.cor-lab.org/git/rsb-performance-monitor.git.dashboards monitoring-dashboards

#. Open the Grafana webpage at http://localhost:8020.

#. On the left side, log in as admin (default: admin:admin).

#. In the left menu, select :menuselection:`Data Sources --> Add new`.

#. Add a data source matching your selected backend.
   For Graphite, the given port is the one used to start the devel server (as described in :doc:`startup`).
   The InfluxDB data source must be called ``influxdb`` and the graphite one ``graphite``.

#. Go to :menuselection:`Dashboards` in the left menu.

#. In the :menuselection:`Home` dropdown menu at the top, select :menuselection:`Import` and import the appropriate dashboards for the selected timeseries database backend from the folder that was cloned in step 1.