README.md

   1 # Tracing helper library
   2
   3 The library creates a configured tracer instance.
   4
   5
   6 ## Usage
   7
   8 Create a tracer instance and set it as a global tracer:
   9
  10 ```go
  11 import (
  12                 "github.com/opentracing/opentracing-go"
  13         "gerrit.o-ran-sc.org/ric-plt/tracelibgo/pkg/tracelibgo"
  14         ...
  15 )
  16
  17 tracer, closer := tracelibgo.CreateTracer("my-service-name")
  18 defer closer.Close()
  19 opentracing.SetGlobalTracer(tracer)
  20 ```
  21
  22 Serialize span context to a byte array that can be sent
  23 to another component via some messaging. For example, using
  24 the RMR library. The serialization uses JSON format.
  25
  26 ```go
  27         carrier := make(map[string]string)
  28         opentracing.GlobalTracer().Inject(
  29                         span.Context(),
  30                         opentracing.TextMap,
  31                         opentracing.TextMapCarrier(carrier))
  32         b, err := json.Marshal(carrier) // b is a []byte and contains serilized span context
  33 ```
  34
  35 Extract a span context from byte array and create a new child span from it.
  36 The serialized span context is got, for example, from the RMR library.
  37
  38 ```go
  39         var carrier map[string]string
  40         err = json.Unmarshal(data, &carrier) // data is []byte containing serialized span context
  41         if err != nil {
  42                 ...
  43         }
  44         context, err := opentracing.GlobalTracer().Extract(opentracing.TextMap, opentracing.TextMapCarrier(carrier))
  45         if err != nil {
  46                 ...
  47         }
  48         span := opentracing.GlobalTracer().StartSpan("go test span", opentracing.ChildOf(context))
  49 ```
  50
  51 ## Configuration
  52
  53 The trace library currently supports only [Jaeger](https://www.jaegertracing.io/) [golang client](https://github.com/jaegertracing/jaeger-client-go) tracer implementation.
  54 The configuration is done using environment variables:
  55
  56 | environment variable         | values                              | default        |
  57 | ---------------------------- |------------------------------------ | -------------- |
  58 | TRACING_ENABLED              | 1, true, 0, false                   | false          |
  59 | TRACING_JAEGER_SAMPLER_TYPE  | const, propabilistic, ratelimiting  | const          |
  60 | TRACING_JAEGER_SAMPLER_PARAM | float                               | 0.001          |
  61 | TRACING_JAEGER_AGENT_ADDR    | IP addr[:port]                      | 127.0.0.1:6831 |
  62 | TRACING_JAEGER_LOG_LEVEL     | all, error, none                    | none           |
  63
  64 Meaning of the configuration variables is described in Jaeger web pages.
  65 By default a no-op tracer is created.
  66
  67
  68 ## Unit testing
  69
  70  GO111MODULE=on go mod download
  71  go test ./pkg/tracelibgo
  72
  73 ## License
  74
  75 See [LICENSES.txt](LICENSES.txt) file.