README.md

   1 # RIC tracing helper library
   2
   3 The library includes a function for creating a configured tracer instance.
   4 It hides the underlaying tracer implementation from the application.
   5
   6 ## Usage
   7
   8 Create a global tracer
   9
  10 ```c
  11     #include <opentracing/tracer.h>
  12     #include <tracelibcpp/tracelibcpp.hpp>
  13
  14     opentracing::Tracer::InitGlobal(tracelibcpp::createTracer("my-service-name"));
  15 ```
  16 Span context propagation between different software components in RIC is using a
  17 TextMap carrier and JSON format serialization.
  18 The [opentracing C++](https://github.com/opentracing/opentracing-cpp) Readme gives examples
  19 how span context **inject** and **extract** with textmap can be done.
  20 Serialization to JSON can be done with any JSON library.
  21
  22 ## Configuration
  23
  24 The trace library currently supports only [Jaeger](https://www.jaegertracing.io/) [C++ client](https://github.com/jaegertracing/jaeger-client-cpp) tracer implementation.
  25 The configuration is done using environment variables:
  26
  27 | environment variable         | values                              | default        |
  28 | ---------------------------- |------------------------------------ | -------------- |
  29 | TRACING_ENABLED              | 1, true, 0, false                   | false          |
  30 | TRACING_JAEGER_SAMPLER_TYPE  | const, propabilistic, ratelimiting  | const          |
  31 | TRACING_JAEGER_SAMPLER_PARAM | float                               | 0.001          |
  32 | TRACING_JAEGER_AGENT_ADDR    | IP addr + port                      | 127.0.0.1:6831 |
  33 | TRACING_JAEGER_LOG_LEVEL     | all, error, none                    | none           |
  34
  35 Meaning of the configuration variables is described in Jaeger web pages.
  36 By default a no-op tracer is created.
  37
  38 ## Requires
  39
  40 cmake
  41 gcc/c++
  42 opentracing-cpp version 1.5.0
  43
  44 ## Build
  45 mkdir build
  46 cd build
  47 cmake ..
  48 make
  49
  50 ## Unit testing
  51 To run unit tests the project needs to be configured with testing option
  52 cmake -DWITH_TESTING=ON ..
  53 make check
  54 Or with output
  55 CTEST_OUTPUT_ON_FAILURE=1 make check
  56
  57 ## Coverage
  58 Unit testing generates also coverage data. To get that in html format run commands, assuming
  59 you are building in `build` dir under the tracelibcpp
  60 ```shell
  61 lcov -c --no-external --base-directory $(dirname $PWD)  --directory . --output-file cov.info
  62 genhtml cov.info
  63 ```
  64
  65 ## Binary package support
  66 Binary packages of the libary can be created with `make package` target, or with
  67 the Dockerfile in the `ci` directory.
  68
  69 The Docker build executes unit tests and compiles binary packages which can then be
  70 exported from the container by running it and giving the target directory as a command line
  71 argument. The target directory must mounted to the container.
  72
  73 ```shell
  74 # Build the container
  75 docker build -t tracelibcpp -f ci/Dockerfile .
  76 # Export binary packages to /tmp
  77 docker run -v /tmp:/tmp tracelibcpp /tmp
  78 ```
  79
  80 ## License
  81
  82 See [LICENSES.txt](LICENSES.txt) file.