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 The library includes a function for creating a configured tracer instance.\r
  34 It hides the underlaying tracer implementation from the application.\r
  35 \r
  36 Tracelib Cpp Repo\r
  37 -----------------\r
  38 \r
  39 .. code:: bash\r
  40 \r
  41  git clone "https://gerrit.o-ran-sc.org/r/ric-plt/tracelibcpp"\r
  42 \r
  43 \r
  44 Usage\r
  45 -----\r
  46 Create a global tracer\r
  47 \r
  48 .. code:: bash\r
  49 \r
  50     #include <opentracing/tracer.h>\r
  51     #include <tracelibcpp/tracelibcpp.hpp>\r
  52 \r
  53     opentracing::Tracer::InitGlobal(tracelibcpp::createTracer("my-service-name"));\r
  54 \r
  55 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
  56 how span context **inject** and **extract** with textmap can be done.\r
  57 Serialization to JSON can be done with any JSON library.\r
  58 \r
  59 Configuration\r
  60 -------------\r
  61 \r
  62 The trace library currently supports only [Jaeger](https://www.jaegertracing.io/) [C++ client](https://github.com/jaegertracing/jaeger-client-cpp) tracer implementation.\r
  63 The configuration is done using environment variables:\r
  64 \r
  65 \r
  66 +------------------------------+-------------------------------------+----------------+\r
  67 | **environment variable**     |             **values**              |  **default**   |\r
  68 |                              |                                     |                | \r
  69 +------------------------------+-------------------------------------+----------------+\r
  70 | TRACING_ENABLED              | 1, true, 0, false                   | false          |\r
  71 |                              |                                     |                | \r
  72 +------------------------------+-------------------------------------+----------------+\r
  73 | TRACING_JAEGER_SAMPLER_TYPE  | const, propabilistic, ratelimiting  | const          |\r
  74 |                              |                                     |                | \r
  75 +------------------------------+-------------------------------------+----------------+\r
  76 | TRACING_JAEGER_SAMPLER_PARAM | float                               | 0.001          |\r
  77 |                              |                                     |                | \r
  78 +------------------------------+-------------------------------------+----------------+\r
  79 | TRACING_JAEGER_AGENT_ADDR    | IP addr + port                      | 127.0.0.1:6831 |\r
  80 |                              |                                     |                | \r
  81 +------------------------------+-------------------------------------+----------------+\r
  82 | TRACING_JAEGER_LOG_LEVEL     | all, error, none                    | none           |\r
  83 |                              |                                     |                | \r
  84 +------------------------------+-------------------------------------+----------------+\r
  85 \r
  86 Meaning of the configuration variables is described in Jaeger web pages.\r
  87 By default a no-op tracer is created.\r
  88 \r
  89 Pre-Requisites\r
  90 --------------\r
  91 \r
  92 * cmake\r
  93 * gcc/c++\r
  94 * opentracing-cpp version 1.5.0\r
  95 \r
  96 Compilation\r
  97 -----------\r
  98 \r
  99 .. code:: bash\r
 100 \r
 101  mkdir build\r
 102  cd build\r
 103  cmake ..\r
 104  make\r
 105 \r
 106 Unit testing\r
 107 ------------\r
 108 To run unit tests the project needs to be configured with testing option\r
 109 \r
 110 .. code:: bash\r
 111 \r
 112  cmake -DWITH_TESTING=ON ..\r
 113  make check\r
 114 \r
 115 Or with output\r
 116 \r
 117 .. code:: bash\r
 118 \r
 119  CTEST_OUTPUT_ON_FAILURE=1 make check\r
 120 \r
 121 Coverage\r
 122 --------\r
 123 \r
 124 \r
 125 Unit testing generates also coverage data. To get that in html format run commands, assuming\r
 126 you are building in `build` dir under the tracelibcpp\r
 127 \r
 128 .. code:: bash\r
 129 \r
 130  lcov -c --no-external --base-directory $(dirname $PWD)  --directory . --output-file cov.info\r
 131  genhtml cov.info\r
 132 \r
 133 Binary package support\r
 134 ----------------------\r
 135 Binary packages of the libary can be created with `make package` target, or with\r
 136 the Dockerfile in the `ci` directory.\r
 137 \r
 138 The Docker build executes unit tests and compiles binary packages which can then be\r
 139 exported from the container by running it and giving the target directory as a command line\r
 140 argument. The target directory must mounted to the container.\r
 141 \r
 142 .. code:: bash\r
 143 \r
 144  docker build -t tracelibcpp -f ci/Dockerfile .\r
 145  # Export binary packages to /tmp\r
 146  docker run -v /tmp:/tmp tracelibcpp /tmp\r
 147 \r