1# Zipkin
2
3## Development and Testing Set-up
4
5Great efforts have been made to make [Zipkin] easier to test, develop and
6experiment against. [Zipkin] can now be run from a single Docker container or by
7running its self-contained executable jar without extensive configuration. In
8its default configuration you will run [Zipkin] with a HTTP collector, In memory
9Span storage backend and web UI on port 9411.
10
11Example:
12```
13docker run -d -p 9411:9411 openzipkin/zipkin
14```
15
16[zipkin]: http://zipkin.io
17
18## Middleware Usage
19
20Follow the [addsvc] example to check out how to wire the [Zipkin] Middleware.
21The changes should be relatively minor.
22
23The [zipkin-go] package has Reporters to send Spans to the [Zipkin] HTTP and
24Kafka Collectors.
25
26### Configuring the Zipkin HTTP Reporter
27
28To use the HTTP Reporter with a [Zipkin] instance running on localhost you
29bootstrap [zipkin-go] like this:
30
31```go
32var (
33 serviceName = "MyService"
34 serviceHostPort = "localhost:8000"
35 zipkinHTTPEndpoint = "http://localhost:9411/api/v2/spans"
36)
37
38// create an instance of the HTTP Reporter.
39reporter := zipkin.NewReporter(zipkinHTTPEndpoint)
40
41// create our tracer's local endpoint (how the service is identified in Zipkin).
42localEndpoint, err := zipkin.NewEndpoint(serviceName, serviceHostPort)
43
44// create our tracer instance.
45tracer, err = zipkin.NewTracer(reporter, zipkin.WithLocalEndpoint(localEndpoint))
46 ...
47
48```
49
50[zipkin-go]: https://github.com/openzipkin/zipkin-go
51[addsvc]: https://github.com/go-kit/examples/tree/master/addsvc
52[Log]: https://github.com/go-kit/kit/tree/master/log
53
54### Tracing Resources
55
56Here is an example of how you could trace resources and work with local spans.
57```go
58import (
59 zipkin "github.com/openzipkin/zipkin-go"
60)
61
62func (svc *Service) GetMeSomeExamples(ctx context.Context, ...) ([]Examples, error) {
63 // Example of annotating a database query:
64 var (
65 spanContext model.SpanContext
66 serviceName = "MySQL"
67 serviceHost = "mysql.example.com:3306"
68 queryLabel = "GetExamplesByParam"
69 query = "select * from example where param = :value"
70 )
71
72 // retrieve the parent span from context to use as parent if available.
73 if parentSpan := zipkin.SpanFromContext(ctx); parentSpan != nil {
74 spanContext = parentSpan.Context()
75 }
76
77 // create the remote Zipkin endpoint
78 ep, _ := zipkin.NewEndpoint(serviceName, serviceHost)
79
80 // create a new span to record the resource interaction
81 span := zipkin.StartSpan(
82 queryLabel,
83 zipkin.Parent(parentSpan.Context()),
84 zipkin.WithRemoteEndpoint(ep),
85 )
86
87 // add interesting key/value pair to our span
88 span.SetTag("query", query)
89
90 // add interesting timed event to our span
91 span.Annotate(time.Now(), "query:start")
92
93 // do the actual query...
94
95 // let's annotate the end...
96 span.Annotate(time.Now(), "query:end")
97
98 // we're done with this span.
99 span.Finish()
100
101 // do other stuff
102 ...
103}
104```
View as plain text