Package list golang-github-go-kit-kit / a531c14
updated tracing/zipkin readme to better clarify span per node vs. span per rpc Bas van Beek 5 years ago
1 changed file(s) with 50 addition(s) and 13 deletion(s). Raw diff Collapse all Expand all
4141 as well as using Go Kit's [Log] package for logging.
4242
4343 ### Span per Node vs. Span per RPC
44 OpenTracing tends to support the `span per node` model, meaning the server and
45 client side of an RPC call are dealt with in separate spans. This diverts from
46 the Zipkin V1 model which is more tailored towards the `span per RPC call` model
47 in which the server and client side annotations of the same RPC call are part of
48 the same span. The [zipkin-go-opentracing] implementation allows you to choose
49 which model you wish to use. Make sure you select the same model consistently
50 for all your services that are required to talk to each other or you will have
51 trace propagation issues. If using non OpenTracing / legacy instrumentation use
52 the `span per RPC call` model.
44 By default Zipkin V1 considers either side of an RPC to have the same identity
45 and differs in that respect from many other tracing systems which consider the
46 caller to be the parent and the receiver the child. The OpenTracing
47 specification does not dictate one model over the other, but the Zipkin team is
48 looking into these [single-host-spans] to potentially bring Zipkin more in-line
49 with the other tracing systems.
5350
54 To adhere to the OpenTracing philosophy the Tracer defaults to `span per node`.
55 To set the `span per RPC call` mode start your tracer like this:
51 [single-host-spans]: https://github.com/openzipkin/zipkin/issues/963
52
53 In case of a `span per node` the receiver will create a child span from the
54 propagated parent span like this:
55
56 ```
57 Span per Node propagation and identities
58
59 CALLER: RECEIVER:
60 ---------------------------------
61 traceId -> traceId
62 spanId (new)
63 spanId -> parentSpanId
64 parentSpanId
65 ```
66
67 **Note:** most tracing implementations supporting the `span per node` model
68 therefore do not propagate their `parentSpanID` as its not needed.
69
70 A typical Zipkin implementation will use the `span per RPC` model and recreate
71 the span identity from the caller on the receiver's end and then annotates its
72 values on top of it. Propagation will happen like this:
73
74 ```
75 Span per RPC propagation and identities
76
77 CALLER: RECEIVER:
78 ---------------------------------
79 traceId -> traceId
80 spanId -> spanId
81 parentSpanId -> parentSpanId
82 ```
83
84 The [zipkin-go-opentracing] implementation allows you to choose which model you
85 wish to use. Make sure you select the same model consistently for all your
86 services that are required to communicate with each other or you will have trace
87 propagation issues. If using non OpenTracing / legacy instrumentation, it's
88 probably best to use the `span per RPC call` model.
89
90 To adhere to the more common tracing philosophy of `span per node`, the Tracer
91 defaults to `span per node`. To set the `span per RPC call` mode start your
92 tracer like this:
5693
5794 ```go
5895 tracer, err = zipkin.NewTracer(
71108 annotation of resources such as databases, caches and other services that do not
72109 have server side tracing support. Since OpenTracing has no specific method of
73110 dealing with these items explicitely that is compatible with Zipkin's `SA`
74 annotation the [zipkin-go-opentracing] has implemented support using the
111 annotation, the [zipkin-go-opentracing] has implemented support using the
75112 OpenTracing Tags system. Here is an example of how one would be able to record
76113 a resource span compatible with standard OpenTracing and triggering an `SA`
77114 annotation in [zipkin-go-opentracing]:
121158 // let's annotate the end...
122159 span.LogEvent("query:end")
123160
124 // we're done with the span. send it to the SpanRecorder for collection...
161 // we're done with this span.
125162 span.Finish()
126163
127164 // do other stuff