Added documentation

Change-Id: Ib529696eccb013f62563dc486585f3b86da3e263
Signed-off-by: wahidw <abdulwahid.w@nokia.com>

diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst
new file mode 100644 (file)
index 0000000..072c0ac
--- /dev/null
+++ b/docs/developer-guide.rst
@@ -0,0 +1,145 @@
+..\r
+.. Copyright (c) 2019 AT&T Intellectual Property.\r
+..\r
+.. Copyright (c) 2019 Nokia.\r
+..\r
+..\r
+.. Licensed under the Creative Commons Attribution 4.0 International\r
+..\r
+.. Public License (the "License"); you may not use this file except\r
+..\r
+.. in compliance with the License. You may obtain a copy of the License at\r
+..\r
+..\r
+..     https://creativecommons.org/licenses/by/4.0/\r
+..\r
+..\r
+.. Unless required by applicable law or agreed to in writing, documentation\r
+..\r
+.. distributed under the License is distributed on an "AS IS" BASIS,\r
+..\r
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+..\r
+.. See the License for the specific language governing permissions and\r
+..\r
+.. limitations under the License.\r
+..\r
+.. This source code is part of the near-RT RIC (RAN Intelligent Controller) platform project (RICP).\r
+..\r
+\r
+Developer Guide\r
+===============\r
+\r
+Clone the golog git repository\r
+--------------------------------------\r
+.. code:: bash\r
+\r
+ git clone "https://gerrit.o-ran-sc.org/r/com/golog"\r
+\r
+Initialization\r
+--------------\r
+\r
+A new logger instance is created with InitLogger function. Process identity is given as a parameter.\r
+\r
+Mapped Diagnostics Context\r
+--------------------------\r
+\r
+The MDCs are key-value pairs, which are included to all log entries by the library.\r
+The MDC pairs are logger instance specific.\r
+\r
+The idea of the MDC is to define values, which stay the same over multiple log writings.\r
+An MDC value set once will appear in all the subsequent logs written with the logger instance.\r
+\r
+A logger instance can be shared by several goroutines.\r
+Respectively, also the MDC values of the logger instance are then shared by them.\r
+When sharing of the MDCs is not desired, separate logger instances should be used.\r
+\r
+Log entry format\r
+----------------\r
+\r
+Each log entry written the library contains\r
+\r
+ * Timestamp\r
+ * Logger identity\r
+ * Log entry severity\r
+ * MDC pairs of the logger instance\r
+ * Log message text\r
+\r
+Currently the library only supports JSON formatted output written to standard out of the process\r
+\r
+*Example log output*\r
+\r
+`{"ts":1551183682974,"crit":"INFO","id":"myprog","mdc":{"second key":"other value","mykey":"keyval"},"msg":"hello world!"}`\r
+\r
+Example\r
+-------\r
+\r
+.. code:: bash\r
+\r
+ package main\r
+\r
+ import (\r
+        mdcloggo "gerrit.o-ran-sc.org/r/com/golog"\r
+ )\r
+\r
+ func main() {\r
+    logger, _ := mdcloggo.InitLogger("myname")\r
+    logger.MdcAdd("mykey", "keyval")\r
+    logger.Info("Some test logs")\r
+ } \r
+\r
+Logging Levels\r
+--------------\r
+\r
+.. code:: bash\r
+\r
+ // ERR is an error level log entry.\r
+   ERR Level = 1\r
+ // WARN is a warning level log entry.\r
+   WARN Level = 2\r
+ // INFO is an info level log entry.\r
+   INFO Level = 3\r
+ // DEBUG is a debug level log entry.\r
+   DEBUG Level = 4\r
+\r
+Golog API's\r
+-----------\r
+\r
+1. LevelSet sets the current logging level.\r
+\r
+.. code:: bash\r
+\r
+ func (l *MdcLogger) LevelSet(level Level) \r
+\r
+\r
+2. LevelGet returns the current logging level.\r
+\r
+.. code:: bash\r
+\r
+ func (l *MdcLogger) LevelGet() Level\r
+\r
+3. MdcAdd adds a new MDC key value pair to the logger.\r
+\r
+.. code:: bash\r
+\r
+ func (l *MdcLogger) MdcAdd(key string, value string)\r
+\r
+4. MdcRemove removes an MDC key from the logger.\r
+\r
+.. code:: bash\r
+\r
+ func (l *MdcLogger) MdcRemove(key string)\r
+\r
+5. MdcGet gets the value of an MDC from the logger.\r
+\r
+.. code:: bash\r
+\r
+ func (l *MdcLogger) MdcGet(key string) (string, bool)\r
+\r
+Description: The function returns the value string and a boolean which tells if the key was found or not.\r
+\r
+6. MdcClean removes all MDC keys from the logger.\r
+\r
+.. code:: bash\r
+\r
+ func (l *MdcLogger) MdcClean()\r

diff --git a/docs/index.rst b/docs/index.rst
index 3d3120a..8d1ccaf 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -36,10 +36,11 @@ Welcome to O-RAN SC golog Documentation
    :caption: Contents:\r
 \r
    overview.rst\r
+   developer-guide.rst\r
    release-notes.rst\r
 \r
 \r
 \r
 * :ref:`genindex`\r
 * :ref:`modindex`\r
-* :ref:`search`
\ No newline at end of file
+* :ref:`search`\r

diff --git a/docs/overview.rst b/docs/overview.rst
index eb99e44..1253236 100644 (file)
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -30,4 +30,4 @@
 golog Overview\r
 ==============\r
 \r
-A Golang implementation of a structured logging library with Mapped Diagnostics Context (MDC) support.
\ No newline at end of file
+A Golang implementation of a structured logging library with Mapped Diagnostics Context (MDC) support.\r