Analysis
********

The monitored services are represented by instances of :mod:`django:django.apps`. Hence,
per type of monitored service a :class:`~django:django.apps.AppConfig` has to be
implemented. For the Happyface project the :class:`~Happyface4.app_configs.AnalysisConfig`
is provided, basing on the :class:`~django:django.apps.AppConfig` class. It provides
convenient methods to create analyses (and their instances) and is described in the
following.

.. tip::
  We *really* recommend using :class:`~Happyface4.app_configs.AnalysisConfig` as a base
  class for every new module.


.. _analysis-config:

The :class:`~Happyface4.app_configs.AnalysisConfig` class
=========================================================

The preferred way of writing a new analysis is by inheriting from
:class:`~Happyface4.app_configs.AnalysisConfig`. This class provides the general structure
for all analyses and should be used for all new or rewrites of modules.

An analysis inheriting from this class is expected to implement the following
methods:

- :meth:`~Happyface4.app_configs.AnalysisConfig.extract_data_from_url`

  This method should implement the retrieval of the data from the external source. It
  could e.g. get data from an elasticsearch index
  (:meth:`~Happyface4.helpers.get_data_from_elasticsearch`).

  The method is expected to return a :class:`dict`, a list of :class:`dicts <dict>` or a
  :class:`list` containing the data. Analyses that are purely trigger-based (e.g.
  ``cms_siteconf_status``, ``vobox_cert_validity``) may simply return a truthy value.

- :meth:`~Happyface4.app_configs.AnalysisConfig.save_data_to_db`

  This method receives the data from
  :meth:`~Happyface4.app_configs.AnalysisConfig.extract_data_from_url`, possibly processes
  it and saves it to the :doc:`database <database>`. For this, the analysis has to
  implement the :doc:`database <database>` models as :mod:`django:django.db.models`.

  The method is expected to return a tuple of :ref:`instance status<instance_status>` and
  a :class:`~datetime.datetime` object.

- :meth:`~Happyface4.app_configs.AnalysisConfig.retrieve_data_from_db`

  This method retrieves the data from the :doc:`database <database>`. It returns a
  :class:`dict` or a :class:`~django.db.models.query.QuerySet` containing the data already
  prepared for use within the :ref:`template<template>` of the analysis.

  The method is expected to return a tuple of said data and the timestamp of the data;
  both are made available in the template as `data` and `timestamp`.

- :meth:`~Happyface4.app_configs.AnalysisConfig.get_instance_status`

  This method returns the status of the analysis instance at time `time`. The optional
  `time_range` (:class:`~datetime.timedelta`) restricts the search for the status to the
  time range between `time - time_range` and `time`.

  The method is expected to return a
  :class:`~django.db.models.query.QuerySet` of :class:`~Happyface4.models.InstanceStatus`
  objects, or a single :class:`~Happyface4.utilities.DummyInstanceStatus` object when no
  status is available in the requested time range.

Happyface regularly (every :mod:`Happyface4.settings` PULL_INTERVAL, normally 15
minutes) calls :meth:`~Happyface4.app_configs.AnalysisConfig.getData` on all analysis
instances, retrieving the data from the external sources. Instances with a
``get_data_every`` larger than 1 are fetched less often (multiples of PULL_INTERVAL). On
HTTP request, i.e. when the user browses the Happyface website,
:meth:`~Happyface4.app_configs.AnalysisConfig.builddiv` is called per instance, generating
the corresponding HTML code.

Two optional attributes/methods alter this behaviour:

- :attr:`~Happyface4.app_configs.AnalysisConfig.instance_parallelization` — when set to
  ``True``, the instances of the analysis are processed in parallel inside ``getData``
  (using a ``ThreadPoolExecutor``). Only enable this for analyses whose instances operate
  on independent data, or rely on proper locking when they share database tables (see e.g.
  ``cms_grafana_timeseries``, ``cms_transfer_errors``).
- :meth:`~Happyface4.app_configs.AnalysisConfig.get_ajax_endpoints` — may be overridden by
  an analysis to declare its AJAX endpoints (URL name, URL kwargs and query parameters) so
  that they are warmed up during cache warmup, preventing empty plots or tables during
  ``getData`` execution.

.. _template:

Template
--------

Django uses a `template engine <https://docs.djangoproject.com/en/6.0/topics/templates/>`_
to render the HTML. Analyses basing on :class:`~Happyface4.app_configs.AnalysisConfig`,
which use the above discussed methods, simply have to provide a template of the form:

.. code-block:: django
  :emphasize-lines: 5

  {% extends "analysis_base.html" %}
  {% block analysis %}
  {% if data %}
  {% load static %}
    [...]
  {% else %}
  <p> No data available for the requested time </p>
  {% endif %}
  {% endblock %}

The part indicated by `[...]` is then to be populated by the data provided by
:meth:`~Happyface4.app_configs.AnalysisConfig.retrieve_data_from_db`, which is available in
the template as `data`.



.. _instance_status:

Instance Statuses
-----------------

Each analysis instance has one of the following statuses at all times:

.. |ok| replace:: ok
.. |warn| replace:: warning
.. |crit| replace:: critical
.. |info| replace:: info
.. |tech| replace:: technical issue

======  =======  =======================================================================
Number  Meaning  Description
======  =======  =======================================================================
0       |ok|     Everything with the service is ok.
1       |warn|   The service is deteriorating. An eye should be kept on it.
2       |crit|   The service is in critical state, actions need to be taken.
-1      |info|   No status can be computed for this instance.
-2      |tech|   There were technical issues getting the data, or within Happyface, such
                 that no reliable information could be computed.
======  =======  =======================================================================

The status of the instance is to be computed in and returned by
:meth:`~Happyface4.app_configs.AnalysisConfig.save_data_to_db`, see
:ref:`above <analysis-config>`. Except for ``is_info`` instances (whose
``save_data_to_db`` returns ``None, None`` and whose status is therefore not persisted),
statuses are internally represented and saved by their numbers. The statuses of the
instances are stored in the :doc:`database <database>`.