docs/developer-guide.rst

   1 ..\r
   2 .. Copyright (c) 2019 AT&T Intellectual Property.\r
   3 ..\r
   4 .. Copyright (c) 2019 Nokia.\r
   5 ..\r
   6 ..\r
   7 .. Licensed under the Creative Commons Attribution 4.0 International\r
   8 ..\r
   9 .. Public License (the "License"); you may not use this file except\r
  10 ..\r
  11 .. in compliance with the License. You may obtain a copy of the License at\r
  12 ..\r
  13 ..\r
  14 ..     https://creativecommons.org/licenses/by/4.0/\r
  15 ..\r
  16 ..\r
  17 .. Unless required by applicable law or agreed to in writing, documentation\r
  18 ..\r
  19 .. distributed under the License is distributed on an "AS IS" BASIS,\r
  20 ..\r
  21 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  22 ..\r
  23 .. See the License for the specific language governing permissions and\r
  24 ..\r
  25 .. limitations under the License.\r
  26 ..\r
  27 ..   This source code is part of the near-RT RIC (RAN Intelligent Controller)\r
  28 ..  platform project (RICP).\r
  29 ..\r
  30 \r
  31 Developer Guide\r
  32 ===============\r
  33 Tracing helper library\r
  34 The library creates a configured tracer instance.\r
  35 \r
  36 Tracelibgo Repo\r
  37 ---------------\r
  38 \r
  39 .. code:: bash\r
  40 \r
  41  git clone "https://gerrit.o-ran-sc.org/r/ric-plt/tracelibgo"\r
  42 \r
  43 \r
  44 Usage\r
  45 -----\r
  46 Create a tracer instance and set it as a global tracer:\r
  47 \r
  48 \r
  49 .. code:: bash\r
  50 \r
  51  import (\r
  52         "github.com/opentracing/opentracing-go"\r
  53         "gerrit.o-ran-sc.org/ric-plt/tracelibgo/pkg/tracelibgo"\r
  54         ...\r
  55  )\r
  56 \r
  57  tracer, closer := tracelibgo.CreateTracer("my-service-name")\r
  58  defer closer.Close()\r
  59  opentracing.SetGlobalTracer(tracer)\r
  60 \r
  61 \r
  62 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
  63 \r
  64 .. code:: bash\r
  65 \r
  66         carrier := make(map[string]string)\r
  67         opentracing.GlobalTracer().Inject(\r
  68                         span.Context(),\r
  69                         opentracing.TextMap,\r
  70                         opentracing.TextMapCarrier(carrier))\r
  71         b, err := json.Marshal(carrier) // b is a []byte and contains serilized span context\r
  72 \r
  73 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
  74 \r
  75 .. code:: bash\r
  76 \r
  77         var carrier map[string]string\r
  78         err = json.Unmarshal(data, &carrier) // data is []byte containing serialized span context\r
  79         if err != nil {\r
  80                 ...\r
  81         }\r
  82         context, err := opentracing.GlobalTracer().Extract(opentracing.TextMap, opentracing.TextMapCarrier(carrier))\r
  83         if err != nil {\r
  84                 ...\r
  85         }\r
  86         span := opentracing.GlobalTracer().StartSpan("go test span", opentracing.ChildOf(context))\r
  87 \r
  88 Configuration\r
  89 -------------\r
  90 \r
  91 The trace library currently supports only [Jaeger](https://www.jaegertracing.io/) [golang client](https://github.com/jaegertracing/jaeger-client-go) tracer implementation.\r
  92 The configuration is done using environment variables:\r
  93 \r
  94 +------------------------------+-------------------------------------+----------------+\r
  95 |  **environment variable**    |        **values**                   | **default**    |\r
  96 |                              |                                     |                |\r
  97 +------------------------------+-------------------------------------+----------------+\r
  98 | TRACING_ENABLED              | 1, true, 0, false                   | false          |\r
  99 |                              |                                     |                |\r
 100 +------------------------------+-------------------------------------+----------------+\r
 101 | TRACING_JAEGER_SAMPLER_TYPE  | const, propabilistic, ratelimiting  | const          |\r
 102 |                              |                                     |                |\r
 103 +------------------------------+-------------------------------------+----------------+\r
 104 | TRACING_JAEGER_SAMPLER_PARAM | float                               | 0.001          |\r
 105 |                              |                                     |                |\r
 106 +------------------------------+-------------------------------------+----------------+\r
 107 | TRACING_JAEGER_AGENT_ADDR    | IP addr[:port]                      | 127.0.0.1:6831 |\r
 108 |                              |                                     |                |\r
 109 +------------------------------+-------------------------------------+----------------+\r
 110 | TRACING_JAEGER_LOG_LEVEL     | all, error, none                    | none           |\r
 111 |                              |                                     |                |\r
 112 +------------------------------+-------------------------------------+----------------+\r
 113 \r
 114 Meaning of the configuration variables is described in Jaeger web pages.\r
 115 By default a no-op tracer is created.\r
 116 \r
 117 \r
 118 Unit testing\r
 119 ------------\r
 120 \r
 121 .. code:: bash\r
 122 \r
 123  GO111MODULE=on go mod download\r
 124  go test ./pkg/tracelibgo\r
 125 \r