.. highlight:: rst

.. _qclog:

#####
qclog
#####

**QClog Daemon**


Description
===========

QClog is an application based on the SeisComP3 framework that receives QC
messages and stores all station parameters in a Round Robin Database(RRD). The
stored station parameters can be visualized in a user friendly way using the
integrated web front-end. The front-end provides three different views: The
admin, the overview and the station page. The first one controls the style of
GUI. The second page gives an overview of all stations received QC messages for.
The latter one shows detailed station information about common QC parameter e.g.
delay, latency and offset.

Requirements
============

* rrdtool 1.4.2 or higher
* Apache HTTP Server
* mod_python - Apache/Python Integration
* Cheetah - The Python-Powered Template Engine
* SeisComP3 Seattle/Jakarta with scqc running

Installation
============

This section describes the installation of the QCLog package. The next steps
assumes that SeisComP3 has been installed in the default installation directory
**/home/sysop/seiscomp3**.

QCLog Service
-------------

1. Run the following command to install the latest QCLog package

.. code-block:: sh

  gsm install qclog

2. Generate the python files from the Cheetah templates with

.. code-block:: sh

  cd seiscomp3/share/qclog/files/
  ./installtemplates.sh

3. Change the SeisComP3 messaging connection if necessary
4. Enable and start the service

.. code-block:: sh

  seiscomp enable qclog
  seiscomp start qclog


QCLog web configuration
-----------------------
Besides the SeisComP3 configuration QCLog uses a separate configuration file
named *qc_config.cfg* which contains several options like for instance the
RRDCache path. Depending on the install environment the path to the file needs
to be adapted to get QCLog running. Available options are:

=================== ==============================================================================
Option              Descritpion
=================== ==============================================================================
RRDpicturepath [1]_ Path to store the generated pictures
RRDpicturepathhtml  Link-path(html) for generated pictures
RRDpath             Index- and rrd-file directory
config              Path of this config file
RRDbinarypath       Path to the binaries of qclog, for generating pictures, etc.
=================== ==============================================================================

The QCLog package ships with an example configuration

1. Create a new QCLog web configuration based on the example template

.. code-block:: sh

  cd seiscomp3/share/qclog/config
  cp qc_config.cfg.example qc_config.cfg

2. Adapt the configuration if necessary

Apache web server integration
-----------------------------

Ubuntu 18.04
------------

1. Open the file **/etc/apache2/envvars** and add the following line

.. code-block:: sh

  export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/home/sysop/install/seiscomp3/lib


2. Create a new file qclog.conf with the following content in the directory **/etc/apache2/sites-available**

.. code-block:: xml

  Alias /qclog /var/www/qclog/
  <Location ~ "/qclog/(stream|admin|overview)">
      PythonPath "['/home/sysop/install/seiscomp3/share/qclog/files/python',
                   '/home/sysop/install/seiscomp3/lib/python/',
                   '/home/sysop/install/seiscomp3/lib/python/seiscomp3'] + sys.path"
      SetHandler mod_python
      PythonHandler qc_handler
      PythonDebug On
  PythonEnablePdb On
  </Location>

  <Directory "/var/www/qclog">
      DirectoryIndex qclog.html
  </Directory>

3. Enable the site and the mod python extension with

.. code-block:: sh

  a2ensite qclog.conf
  a2enmod python

4. Restart the Apache web server

.. code-block:: sh

  service apache2 restart

Crontab
--------
The QCLog overview page will not be generated automatically by the service. One option
to trigger the creation of the page is a crontab entry.

1. Open the cron tab editor

.. code-block:: sh

    crontab -e

2. To update the overview page every five minutes add the following line

.. code-block:: sh

    */5 * * * * cd $SC3_INSTALL_DIR/share/qclog/files/python/ && $SC3_INSTALL_DIR/bin/seiscomp exec python qc_index.py > ../html/qclog.html

3. Save the changes

.. [1] The directory must **exist** and the www-data user needs write access to the
       specified directory.



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

| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/qclog.cfg`
| :file:`etc/global.cfg`
| :file:`etc/qclog.cfg`
| :file:`~/.seiscomp3/global.cfg`
| :file:`~/.seiscomp3/qclog.cfg`

qclog inherits :ref:`global options<global-configuration>`.




Command-line
============

.. program:: qclog

.. option:: -h, --help

   show a help message and exit

.. option:: --enums

   set for the old Qcmessage

.. option:: --inventory

   load the stations out of the inventory and create all
   rrd's and index\-files\(Overwrite old rrd's\)
   Default:write the rrd\- and index\-files on the fly