source: main/waeup.kofa/trunk/docs/source/userdocs/datacenter/logging.rst @ 12891

.. _logging:

Logfiles
********

Kofa is logging actions, which cause changes to the database or the filesystem, in separate human-redable event logfiles. Nearly all actions are being logged except those committed by applicants and students during registration periods. During these data initialization periods, applicants and students are requested to edit many fields and upload heaps of scanned documents. Logging all these changes would mean filling the logfiles with more or less useless or redundant information. The main purpose of Kofa's logging facilities is to trace changes effected by portal officers. Applicants and students can only access their own data. They don't have the permission to change anything else. Whereas portal officers bear responsibility for the integrity of the whole database. Depending on the roles they have, officers can add, edit or remove application and study data without leaving a trace in the object database itself. Kofa closes this security gap by recording nearly all actions of portal officers into various event logfiles.

.. note::

 Kofa logs the changing but not the viewing of data (except downloading export files or reports). Also entering (login) end leaving (logout) the portal is **not** being recorded.

Critics may claim that extensive logging may discourage officers from working with the portal. Persons in key functions often don't want to be controlled or supervised by anybody else. Indeed, Kofa does not respond to the desire for this kind of privacy. Datacenter managers can search all logfiles and can even see what their principles have done with the data. Goal behind is **transparency and security**, i.e. transparent data processing and reduction of the vulnerability to corruption combined with cutting-edge technologies to protect the data against attacks from outside.

Logfiles can not be accessed directly. They can neither be downloaded nor viewed entirely online. But the files can be searched online for arbitrary `regular expressions`_. The simplest regular expression is a single word or a string. A technical description, how logfiles are being querried, can be found :py:meth:`here<waeup.kofa.datacenter.DataCenter.queryLogfiles>`.

Each line in the logfile means a single log entry. It is composed of four parts: a datetime string, the log level (mainly 'INFO'), the id of the logged-in user, and a message part. Depending on the module, the message part is subdivided into further parts which are described below.


main.log
========

All actions in the academic section are logged in ``main.log``. Changes of faculties, departments, certificates, courses and certificate courses done via pages in the user interface (browser page) are recorded in the following form::

  2014-12-11 13:09:22,855 - INFO - admin - browser.pages.DepartmentAddFormPage - added: FAC1/DEP1
  2014-12-11 13:19:31,755 - INFO - admin - browser.pages.DepartmentManageFormPage - DEP1 - saved: title
  2014-12-12 13:19:43,255 - INFO - admin - browser.pages.FacultyManageFormPage - removed: DEP1

The message part is composed of the browser page name and the action taken. In the example above a department ``DEP1`` was added on December 11, 2014 by user ``admin`` in faculty ``FAC1``, the title was changed 10 minutes later and, finally, the department was entirely removed one day later. In the same way user data and configuration data are logged in the main logfile. Examples::


  2015-04-01 08:33:47,474 - INFO - admin - browser.pages.UserManageFormPage - Test edited: roles
  2015-04-27 09:39:24,073 - INFO - admin - browser.pages.SessionConfigurationAddFormPage - added: 2014

Furthermore, ``main.log`` does contain information about reports::

  2015-04-28 15:34:31,852 - INFO - admin - students.reports.student_statistics.StudentStatisticsReportGeneratorPage - report 3029 created: Student Statistics (session=1989, mode=All, breakdown=faccode)
  2015-04-28 15:34:37,698 - INFO - admin - students.reports.student_statistics.StudentStatisticsReportPDFView - report 3029 downloaded: StudentStatisticsReport_1989_1990_All_2015-04-28_13-34-36_UTC.pdf
  2015-04-28 15:36:30,106 - INFO - admin - browser.reports.ReportsContainerPage - report 3029 discarded

the management of documents::

  2015-01-09 17:30:49,819 - INFO - admin - HOWTO - Document created
  2015-01-09 17:30:49,822 - INFO - admin - documents.browser.DocumentAddFormPage - added: REST Document HOWTO

password change requests and the usage of password mandates::

  2015-04-28 13:42:52,753 - INFO - zope.anybody - browser.pages.ChangePasswordRequestPage - B1234567 - myname@gmail.com
  2015-04-28 13:43:51,056 - INFO - zope.anybody - PasswordMandate used: B1234567

``zope.anybody`` is the user id of anonnymous (non-logged-in) users.

Some log entries do not contain information about a browser page. These entries were generated deeper in the system. The ``Document created`` entry, for example, was added by a workflow transition. The ``PasswordMandate used`` entry was added by :py:meth:`waeup.kofa.mandates.mandate.PasswordMandate.execute` and not directly by the browser page which calls this method (:py:meth:`waeup.kofa.mandates.browser.MandateView.update`).

``main.log`` is also the place where plugins store information about system upgrades. If catalogs have to be re-indexed or new attributes of objects have to
be initialized, a corresponding message is stored in the main logfile.


datacenter.log
==============


accesscodes.log
===============


applicants.log
==============


students.log
============


payments.log
============


hostels.log
===========




.. _regular expressions: http://en.wikipedia.org/wiki/Regular_expression