From 21e1caa5d7343bbb1c46e9909e6173a08f1708ae Mon Sep 17 00:00:00 2001 From: Nikolay Starodubtsev Date: Fri, 3 Apr 2015 14:35:54 +0300 Subject: [PATCH] Add Sahara log guideliness During Kilo cycle we design and implement the new way of creating logs in Sahara project. Now we add a document which describe our vision on it. Change-Id: I5f3c215600475a012d335d415fa826e1d4aa2cd8 --- doc/source/devref/log.guidelines.rst | 53 ++++++++++++++++++++++++++++ doc/source/index.rst | 1 + 2 files changed, 54 insertions(+) create mode 100644 doc/source/devref/log.guidelines.rst diff --git a/doc/source/devref/log.guidelines.rst b/doc/source/devref/log.guidelines.rst new file mode 100644 index 00000000..e8c56ecc --- /dev/null +++ b/doc/source/devref/log.guidelines.rst @@ -0,0 +1,53 @@ + +Log Guidelines +====================== + +Levels Guidelines +----------------- + +During Kilo release cycle Sahara community defined the following log levels: + + +* Debug: Shows everything and is likely not suitable for normal production + operation due to the sheer size of logs generated (e.g. scripts executions, + process execution, etc.). +* Info: Usually indicates successful service start/stop, versions and such + non-error related data. This should include largely positive units of work + that are accomplished (e.g. service setup, cluster start, successful job + execution). +* Warning: Indicates that there might be a systemic issue; + potential predictive failure notice (e.g. job execution failed). +* Error: An error has occurred and an administrator should research the event + (e.g. cluster failed to start, plugin violations of operation). +* Critical: An error has occurred and the system might be unstable, anything + that eliminates part of Sahara's intended functionality; immediately get + administrator assistance (e.g. failed to access keystone/database, plugin + load failed). + + +Formatting Guidelines +---------------------- + +Now Sahara uses string formatting defined in `PEP 3101`_ for logs. + +.. code:: python + + LOG.warning(_LW("Incorrect path: {path}").format(path=path)) + + +.. + + +Translation Guidelines +---------------------- + +All log levels except Debug requires translation. None of the separate cli tools packaged +with Sahara contain log translations. + +* Debug: no translation +* Info: _LI +* Warning: _LW +* Error: _LE +* Critical: _LC + +.. _PEP 3101: https://www.python.org/dev/peps/pep-3101/ diff --git a/doc/source/index.rst b/doc/source/index.rst index c007db3f..2384071d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -92,6 +92,7 @@ Developer Guide devref/how_to_build_oozie devref/adding_database_migrations devref/testing + devref/log.guidelines **Background Concepts for Sahara**