Documentation for tracelibcpp

Change-Id: Idcfa5e514525c8ef3a6be5c5d34ace5f14b8c95f
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..e29cfcd
--- /dev/null
+++ b/docs/developer-guide.rst
@@ -0,0 +1,147 @@
+..\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)\r
+.. platform project (RICP).\r
+..\r
+\r
+Developer Guide\r
+===============\r
+The library includes a function for creating a configured tracer instance.\r
+It hides the underlaying tracer implementation from the application.\r
+\r
+Tracelib Cpp Repo\r
+-----------------\r
+\r
+.. code:: bash\r
+\r
+ git clone "https://gerrit.o-ran-sc.org/r/ric-plt/tracelibcpp"\r
+\r
+\r
+Usage\r
+-----\r
+Create a global tracer\r
+\r
+.. code:: bash\r
+\r
+    #include <opentracing/tracer.h>\r
+    #include <tracelibcpp/tracelibcpp.hpp>\r
+\r
+    opentracing::Tracer::InitGlobal(tracelibcpp::createTracer("my-service-name"));\r
+\r
+Span context propagation between different software components in RIC is using a TextMap carrier and JSON format serialization. The [opentracing C++](https://github.com/opentracing/opentracing-cpp) Readme gives examples\r
+how span context **inject** and **extract** with textmap can be done.\r
+Serialization to JSON can be done with any JSON library.\r
+\r
+Configuration\r
+-------------\r
+\r
+The trace library currently supports only [Jaeger](https://www.jaegertracing.io/) [C++ client](https://github.com/jaegertracing/jaeger-client-cpp) tracer implementation.\r
+The configuration is done using environment variables:\r
+\r
+\r
++------------------------------+-------------------------------------+----------------+\r
+| **environment variable**     |             **values**              |  **default**   |\r
+|                              |                                     |                | \r
++------------------------------+-------------------------------------+----------------+\r
+| TRACING_ENABLED              | 1, true, 0, false                   | false          |\r
+|                              |                                     |                | \r
++------------------------------+-------------------------------------+----------------+\r
+| TRACING_JAEGER_SAMPLER_TYPE  | const, propabilistic, ratelimiting  | const          |\r
+|                              |                                     |                | \r
++------------------------------+-------------------------------------+----------------+\r
+| TRACING_JAEGER_SAMPLER_PARAM | float                               | 0.001          |\r
+|                              |                                     |                | \r
++------------------------------+-------------------------------------+----------------+\r
+| TRACING_JAEGER_AGENT_ADDR    | IP addr + port                      | 127.0.0.1:6831 |\r
+|                              |                                     |                | \r
++------------------------------+-------------------------------------+----------------+\r
+| TRACING_JAEGER_LOG_LEVEL     | all, error, none                    | none           |\r
+|                              |                                     |                | \r
++------------------------------+-------------------------------------+----------------+\r
+\r
+Meaning of the configuration variables is described in Jaeger web pages.\r
+By default a no-op tracer is created.\r
+\r
+Pre-Requisites\r
+--------------\r
+\r
+* cmake\r
+* gcc/c++\r
+* opentracing-cpp version 1.5.0\r
+\r
+Compilation\r
+-----------\r
+\r
+.. code:: bash\r
+\r
+ mkdir build\r
+ cd build\r
+ cmake ..\r
+ make\r
+\r
+Unit testing\r
+------------\r
+To run unit tests the project needs to be configured with testing option\r
+\r
+.. code:: bash\r
+\r
+ cmake -DWITH_TESTING=ON ..\r
+ make check\r
+\r
+Or with output\r
+\r
+.. code:: bash\r
+\r
+ CTEST_OUTPUT_ON_FAILURE=1 make check\r
+\r
+Coverage\r
+--------\r
+\r
+\r
+Unit testing generates also coverage data. To get that in html format run commands, assuming\r
+you are building in `build` dir under the tracelibcpp\r
+\r
+.. code:: bash\r
+\r
+ lcov -c --no-external --base-directory $(dirname $PWD)  --directory . --output-file cov.info\r
+ genhtml cov.info\r
+\r
+Binary package support\r
+----------------------\r
+Binary packages of the libary can be created with `make package` target, or with\r
+the Dockerfile in the `ci` directory.\r
+\r
+The Docker build executes unit tests and compiles binary packages which can then be\r
+exported from the container by running it and giving the target directory as a command line\r
+argument. The target directory must mounted to the container.\r
+\r
+.. code:: bash\r
+\r
+ docker build -t tracelibcpp -f ci/Dockerfile .\r
+ # Export binary packages to /tmp\r
+ docker run -v /tmp:/tmp tracelibcpp /tmp\r
+\r

diff --git a/docs/index.rst b/docs/index.rst
index 1b4c57c..a1fc49c 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -36,10 +36,11 @@ Welcome to O-RAN SC tracelibcpp 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