Documentation for tracelibgo

Change-Id: I213867deeea7ccffa5fdce596148eb0bf43d1703
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..ece6754
--- /dev/null
+++ b/docs/developer-guide.rst
@@ -0,0 +1,125 @@
+..\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
+Tracing helper library\r
+The library creates a configured tracer instance.\r
+\r
+Tracelibgo Repo\r
+---------------\r
+\r
+.. code:: bash\r
+\r
+ git clone "https://gerrit.o-ran-sc.org/r/ric-plt/tracelibgo"\r
+\r
+\r
+Usage\r
+-----\r
+Create a tracer instance and set it as a global tracer:\r
+\r
+\r
+.. code:: bash\r
+\r
+ import (\r
+        "github.com/opentracing/opentracing-go"\r
+        "gerrit.o-ran-sc.org/ric-plt/tracelibgo/pkg/tracelibgo"\r
+        ...\r
+ )\r
+\r
+ tracer, closer := tracelibgo.CreateTracer("my-service-name")\r
+ defer closer.Close()\r
+ opentracing.SetGlobalTracer(tracer)\r
+\r
+\r
+Serialize span context to a byte array that can be sent to another component via some messaging. For example, using the RMR library. The serialization uses JSON format.\r
+\r
+.. code:: bash\r
+\r
+        carrier := make(map[string]string)\r
+        opentracing.GlobalTracer().Inject(\r
+                        span.Context(),\r
+                        opentracing.TextMap,\r
+                        opentracing.TextMapCarrier(carrier))\r
+        b, err := json.Marshal(carrier) // b is a []byte and contains serilized span context\r
+\r
+Extract a span context from byte array and create a new child span from it.The serialized span context is got, for example, from the RMR library.\r
+\r
+.. code:: bash\r
+\r
+        var carrier map[string]string\r
+        err = json.Unmarshal(data, &carrier) // data is []byte containing serialized span context\r
+        if err != nil {\r
+                ...\r
+        }\r
+        context, err := opentracing.GlobalTracer().Extract(opentracing.TextMap, opentracing.TextMapCarrier(carrier))\r
+        if err != nil {\r
+                ...\r
+        }\r
+        span := opentracing.GlobalTracer().StartSpan("go test span", opentracing.ChildOf(context))\r
+\r
+Configuration\r
+-------------\r
+\r
+The trace library currently supports only [Jaeger](https://www.jaegertracing.io/) [golang client](https://github.com/jaegertracing/jaeger-client-go) tracer implementation.\r
+The configuration is done using environment variables:\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
+\r
+Unit testing\r
+------------\r
+\r
+.. code:: bash\r
+\r
+ GO111MODULE=on go mod download\r
+ go test ./pkg/tracelibgo\r
+\r

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