--- /dev/null
+..\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