vendor/github.com/go-kit/kit/tracing/zipkin/README.md

   1 # Zipkin
   2
   3 ## Development and Testing Set-up
   4
   5 Great efforts have been made to make [Zipkin] easier to test, develop and
   6 experiment against. [Zipkin] can now be run from a single Docker container or by
   7 running its self-contained executable jar without extensive configuration. In
   8 its default configuration you will run Zipkin with a HTTP collector, In memory
   9 Span storage backend and web UI on port 9411.
  10
  11 Example:
  12 ```
  13 docker run -d -p 9411:9411 openzipkin/zipkin
  14 ```
  15
  16 [zipkin]: http://zipkin.io
  17
  18 Instrumenting your services with Zipkin distributed tracing using the default
  19 configuration is now possible with the latest release of [zipkin-go-opentracing]
  20 as it includes an HTTP transport for sending spans to the [Zipkin] HTTP
  21 Collector.
  22
  23 ## Middleware Usage
  24
  25 Follow the [addsvc] example to check out how to wire the Zipkin Middleware. The
  26 changes should be relatively minor.
  27
  28 The [zipkin-go-opentracing] package has support for HTTP, Kafka and Scribe
  29 collectors as well as using Go Kit's [Log] package for logging.
  30
  31 ### Configuring for the Zipkin HTTP Collector
  32
  33 To select the transport for the HTTP Collector, you configure the `Recorder`
  34 with the appropriate collector like this:
  35
  36 ```go
  37 var (
  38   debugMode          = false
  39   serviceName        = "MyService"
  40   serviceHostPort    = "localhost:8000"
  41   zipkinHTTPEndpoint = "localhost:9411"
  42 )
  43 collector, err = zipkin.NewHTTPCollector(zipkinHTTPEndpoint)
  44 if err != nil {
  45   // handle error
  46 }
  47 tracer, err = zipkin.NewTracer(
  48   zipkin.NewRecorder(collector, debugMode, serviceHostPort, serviceName),
  49   ...
  50 )
  51 ```
  52
  53 ### Span per Node vs. Span per RPC
  54 By default Zipkin V1 considers either side of an RPC to have the same identity
  55 and differs in that respect from many other tracing systems which consider the
  56 caller to be the parent and the receiver to be the child. The OpenTracing
  57 specification does not dictate one model over the other, but the Zipkin team is
  58 looking into these [single-host-spans] to potentially bring Zipkin more in-line
  59 with the other tracing systems.
  60
  61 [single-host-spans]: https://github.com/openzipkin/zipkin/issues/963
  62
  63 In case of a `span per node` the receiver will create a child span from the
  64 propagated parent span like this:
  65
  66 ```
  67 Span per Node propagation and identities
  68
  69 CALLER:            RECEIVER:
  70 ---------------------------------
  71 traceId        ->  traceId
  72                    spanId (new)
  73 spanId         ->  parentSpanId
  74 parentSpanId
  75 ```
  76
  77 **Note:** most tracing implementations supporting the `span per node` model
  78 therefore do not propagate their `parentSpanID` as its not needed.
  79
  80 A typical Zipkin implementation will use the `span per RPC` model and recreate
  81 the span identity from the caller on the receiver's end and then annotates its
  82 values on top of it. Propagation will happen like this:
  83
  84 ```
  85 Span per RPC propagation and identities
  86
  87 CALLER:            RECEIVER:
  88 ---------------------------------
  89 traceId        ->  traceId
  90 spanId         ->  spanId
  91 parentSpanId   ->  parentSpanId
  92 ```
  93
  94 The [zipkin-go-opentracing] implementation allows you to choose which model you
  95 wish to use. Make sure you select the same model consistently for all your
  96 services that are required to communicate with each other or you will have trace
  97 propagation issues. If using non OpenTracing / legacy instrumentation, it's
  98 probably best to use the `span per RPC call` model.
  99
 100 To adhere to the more common tracing philosophy of `span per node`, the Tracer
 101 defaults to `span per node`. To set the `span per RPC call` mode start your
 102 tracer like this:
 103
 104 ```go
 105 tracer, err = zipkin.NewTracer(
 106         zipkin.NewRecorder(...),
 107         zipkin.ClientServerSameSpan(true),
 108 )
 109 ```
 110
 111 [zipkin-go-opentracing]: https://github.com/openzipkin/zipkin-go-opentracing
 112 [addsvc]:https://github.com/go-kit/kit/tree/master/examples/addsvc
 113 [Log]: https://github.com/go-kit/kit/tree/master/log
 114
 115 ### Tracing Resources
 116
 117 In our legacy implementation we had the `NewChildSpan` method to allow
 118 annotation of resources such as databases, caches and other services that do not
 119 have server side tracing support. Since OpenTracing has no specific method of
 120 dealing with these items explicitely that is compatible with Zipkin's `SA`
 121 annotation, the [zipkin-go-opentracing] has implemented support using the
 122 OpenTracing Tags system. Here is an example of how one would be able to record
 123 a resource span compatible with standard OpenTracing and triggering an `SA`
 124 annotation in [zipkin-go-opentracing]:
 125
 126 ```go
 127 // you need to import the ext package for the Tag helper functions
 128 import (
 129         "github.com/opentracing/opentracing-go"
 130         "github.com/opentracing/opentracing-go/ext"
 131 )
 132
 133 func (svc *Service) GetMeSomeExamples(ctx context.Context, ...) ([]Examples, error) {
 134         // Example of annotating a database query:
 135         var (
 136                 serviceName = "MySQL"
 137                 serviceHost = "mysql.example.com"
 138                 servicePort = uint16(3306)
 139                 queryLabel  = "GetExamplesByParam"
 140                 query       = "select * from example where param = 'value'"
 141         )
 142
 143         // retrieve the parent span, if not found create a new trace
 144         parentSpan := opentracing.SpanFromContext(ctx)
 145         if parentSpan == nil {
 146                 parentSpan = opentracing.StartSpan(queryLabel)
 147     defer parentSpan.Finish()
 148         }
 149
 150         // create a new span to record the resource interaction
 151         span := opentracing.StartChildSpan(parentSpan, queryLabel)
 152
 153         // span.kind "resource" triggers SA annotation
 154         ext.SpanKind.Set(span, "resource")
 155
 156         // this will label the span's service & hostPort (called Endpoint in Zipkin)
 157         ext.PeerService.Set(span, serviceName)
 158         ext.PeerHostname.Set(span, serviceHost)
 159         ext.PeerPort.Set(span, servicePort)
 160
 161         // a Tag is the equivalent of a Zipkin Binary Annotation (key:value pair)
 162         span.SetTag("query", query)
 163
 164         // a LogEvent is the equivalent of a Zipkin Annotation (timestamped)
 165         span.LogEvent("query:start")
 166
 167         // do the actual query...
 168
 169         // let's annotate the end...
 170         span.LogEvent("query:end")
 171
 172         // we're done with this span.
 173         span.Finish()
 174
 175         // do other stuff
 176         ...
 177 }
 178 ```