Commit a531c14ad772e376cd6603eef28403ca2acee703 - golang-github-go-kit-kit

updated tracing/zipkin readme to better clarify span per node vs. span per rpc Bas van Beek 7 years ago

1 changed file(s) with 50 addition(s) and 13 deletion(s). Raw diff Collapse all Expand all

+50

-13

tracing/zipkin/README.md less more

41	41	as well as using Go Kit's [Log] package for logging.
42	42
43	43	### 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.
53	50
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:
56	93
57	94	```go
58	95	tracer, err = zipkin.NewTracer(

71	108	annotation of resources such as databases, caches and other services that do not
72	109	have server side tracing support. Since OpenTracing has no specific method of
73	110	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
75	112	OpenTracing Tags system. Here is an example of how one would be able to record
76	113	a resource span compatible with standard OpenTracing and triggering an `SA`
77	114	annotation in [zipkin-go-opentracing]:

121	158	// let's annotate the end...
122	159	span.LogEvent("query:end")
123	160
124		// we're done with the span. send it to the SpanRecorder for collection...
	161	// we're done with this span.
125	162	span.Finish()
126	163
127	164	// do other stuff