3 ## Development and Testing Set-up
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.
13 docker run -d -p 9411:9411 openzipkin/zipkin
16 [zipkin]: http://zipkin.io
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
25 Follow the [addsvc] example to check out how to wire the Zipkin Middleware. The
26 changes should be relatively minor.
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.
31 ### Configuring for the Zipkin HTTP Collector
33 To select the transport for the HTTP Collector, you configure the `Recorder`
34 with the appropriate collector like this:
39 serviceName = "MyService"
40 serviceHostPort = "localhost:8000"
41 zipkinHTTPEndpoint = "localhost:9411"
43 collector, err = zipkin.NewHTTPCollector(zipkinHTTPEndpoint)
47 tracer, err = zipkin.NewTracer(
48 zipkin.NewRecorder(collector, debugMode, serviceHostPort, serviceName),
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.
61 [single-host-spans]: https://github.com/openzipkin/zipkin/issues/963
63 In case of a `span per node` the receiver will create a child span from the
64 propagated parent span like this:
67 Span per Node propagation and identities
70 ---------------------------------
73 spanId -> parentSpanId
77 **Note:** most tracing implementations supporting the `span per node` model
78 therefore do not propagate their `parentSpanID` as its not needed.
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:
85 Span per RPC propagation and identities
88 ---------------------------------
91 parentSpanId -> parentSpanId
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.
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
105 tracer, err = zipkin.NewTracer(
106 zipkin.NewRecorder(...),
107 zipkin.ClientServerSameSpan(true),
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
115 ### Tracing Resources
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]:
127 // you need to import the ext package for the Tag helper functions
129 "github.com/opentracing/opentracing-go"
130 "github.com/opentracing/opentracing-go/ext"
133 func (svc *Service) GetMeSomeExamples(ctx context.Context, ...) ([]Examples, error) {
134 // Example of annotating a database query:
136 serviceName = "MySQL"
137 serviceHost = "mysql.example.com"
138 servicePort = uint16(3306)
139 queryLabel = "GetExamplesByParam"
140 query = "select * from example where param = 'value'"
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()
150 // create a new span to record the resource interaction
151 span := opentracing.StartChildSpan(parentSpan, queryLabel)
153 // span.kind "resource" triggers SA annotation
154 ext.SpanKind.Set(span, "resource")
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)
161 // a Tag is the equivalent of a Zipkin Binary Annotation (key:value pair)
162 span.SetTag("query", query)
164 // a LogEvent is the equivalent of a Zipkin Annotation (timestamped)
165 span.LogEvent("query:start")
167 // do the actual query...
169 // let's annotate the end...
170 span.LogEvent("query:end")
172 // we're done with this span.