From: wahidw <abdulwahid.w@nokia.com>
Date: Sun, 23 Aug 2020 08:15:41 +0000 (+0530)
Subject: Added documentation
X-Git-Tag: v0.0.2~1
X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=cbf51a930068538cbd4eebdd879fa7c87b95e1d7;p=com%2Fgolog.git

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