From a3bc2943f6faf820e951d31efeda2d1783ef5a70 Mon Sep 17 00:00:00 2001
From: Alexey Khivin <akhivin@mirantis.com>
Date: Fri, 2 Oct 2015 21:14:27 +0300
Subject: [PATCH] MuranoPL logging tutorial added

Change-Id: I341f04d6eef64d20e256ae461dea1775ee41fc9f
---
 .../appdev-guide/murano_pl/core_classes.rst   | 63 +++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/doc/source/draft/appdev-guide/murano_pl/core_classes.rst b/doc/source/draft/appdev-guide/murano_pl/core_classes.rst
index c291ede7..57fd5c44 100644
--- a/doc/source/draft/appdev-guide/murano_pl/core_classes.rst
+++ b/doc/source/draft/appdev-guide/murano_pl/core_classes.rst
@@ -9,3 +9,66 @@ Murano core library is a set of classes needed in every deployment as
 helpers for application classes. This library is located under the
 `meta <http://git.openstack.org/cgit/openstack/murano/tree/meta/io.murano/>`_
 directory.
+
+Logging API
+-----------
+
+Logging API is the part of core library since Liberty release. It was
+introduced to improve debuggability of MuranoPL programs.
+
+You can get a logger instance by calling a ``logger`` function which is located
+in  ``io.murano.system`` namespace. The ``logger`` function takes a logger name as the
+only parameter. It is a common recommendation to use full class name as a
+logger name within that class. This convention avoids names conflicts
+in logs and ensures a better logging subsystem configurability.
+
+Logger class instantiation::
+
+    $log: logger('io.murano.apps.activeDirectory.ActiveDirectory')
+
+
+There are several methods you can use for logging events: ``debug``,
+``trace``, ``info``, ``warning``, ``error``, ``critical`` that correspond
+to the log levels.
+
+Log levels prioritized in order of severity:
+
+============  ===========
+Level         Description
+============  ===========
+CRITICAL      The CRITICAL level designates very severe error events that will presumably lead the application to abort.
+ERROR         The ERROR level designates error events that might still allow the application to continue running.
+INFO          The INFO level designates informational messages that highlight the progress of the application at the coarse-grained level.
+DEBUG         The DEBUG level designates fine-grained informational events that are most useful to debug an application.
+TRACE         The TRACE level designates finer-grained informational events than the DEBUG level.
+============  ===========
+
+Logging example::
+
+    $log.info('print my info message {message}', message=>message)
+
+Logging methods use the same format rules as the YAQL ``format`` function.
+Thus the line above is equal to the::
+
+    $log.info('print my info message {message}'.format(message=>message))
+
+To print an exception stacktrace, use the ``exception`` method.
+This method uses the `ERROR` level.
+
+Logging exception::
+
+  Try:
+    - Throw: exceptionName
+      Message: exception message
+  Catch:
+  With: exceptionName
+  As: e
+  Do:
+    - $log.exception($e, 'something bad happen "{message}"', message=>message)
+
+
+.. NOTE::
+    You can configure the logging subsystem via `logging.conf` of the Murano
+    Engine. The Murano Engine configuration lays beyond the MuranoPL tutorial.
+    Refer to the Murano or the oslo.log tutorials for more information on how
+    to configure logs.