README.md
1[](https://gitter.im/opentracing/public) [](https://travis-ci.org/opentracing/opentracing-go) [](http://godoc.org/github.com/opentracing/opentracing-go)
2
3# OpenTracing API for Go
4
5This package is a Go platform API for OpenTracing.
6
7## Required Reading
8
9In order to understand the Go platform API, one must first be familiar with the
10[OpenTracing project](http://opentracing.io) and
11[terminology](http://opentracing.io/documentation/pages/spec.html) more specifically.
12
13## API overview for those adding instrumentation
14
15Everyday consumers of this `opentracing` package really only need to worry
16about a couple of key abstractions: the `StartSpan` function, the `Span`
17interface, and binding a `Tracer` at `main()`-time. Here are code snippets
18demonstrating some important use cases.
19
20#### Singleton initialization
21
22The simplest starting point is `./default_tracer.go`. As early as possible, call
23
24```go
25 import "github.com/opentracing/opentracing-go"
26 import ".../some_tracing_impl"
27
28 func main() {
29 opentracing.InitGlobalTracer(
30 // tracing impl specific:
31 some_tracing_impl.New(...),
32 )
33 ...
34 }
35```
36
37##### Non-Singleton initialization
38
39If you prefer direct control to singletons, manage ownership of the
40`opentracing.Tracer` implementation explicitly.
41
42#### Creating a Span given an existing Go `context.Context`
43
44If you use `context.Context` in your application, OpenTracing's Go library will
45happily rely on it for `Span` propagation. To start a new (blocking child)
46`Span`, you can use `StartSpanFromContext`.
47
48```go
49 func xyz(ctx context.Context, ...) {
50 ...
51 span, ctx := opentracing.StartSpanFromContext(ctx, "operation_name")
52 defer span.Finish()
53 span.LogFields(
54 log.String("event", "soft error"),
55 log.String("type", "cache timeout"),
56 log.Int("waited.millis", 1500))
57 ...
58 }
59```
60
61#### Starting an empty trace by creating a "root span"
62
63It's always possible to create a "root" `Span` with no parent or other causal
64reference.
65
66```go
67 func xyz() {
68 ...
69 sp := opentracing.StartSpan("operation_name")
70 defer sp.Finish()
71 ...
72 }
73```
74
75#### Creating a (child) Span given an existing (parent) Span
76
77```go
78 func xyz(parentSpan opentracing.Span, ...) {
79 ...
80 sp := opentracing.StartSpan(
81 "operation_name",
82 opentracing.ChildOf(parentSpan.Context()))
83 defer sp.Finish()
84 ...
85 }
86```
87
88#### Serializing to the wire
89
90```go
91 func makeSomeRequest(ctx context.Context) ... {
92 if span := opentracing.SpanFromContext(ctx); span != nil {
93 httpClient := &http.Client{}
94 httpReq, _ := http.NewRequest("GET", "http://myservice/", nil)
95
96 // Transmit the span's TraceContext as HTTP headers on our
97 // outbound request.
98 opentracing.GlobalTracer().Inject(
99 span.Context(),
100 opentracing.HTTPHeaders,
101 opentracing.HTTPHeadersCarrier(httpReq.Header))
102
103 resp, err := httpClient.Do(httpReq)
104 ...
105 }
106 ...
107 }
108```
109
110#### Deserializing from the wire
111
112```go
113 http.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
114 var serverSpan opentracing.Span
115 appSpecificOperationName := ...
116 wireContext, err := opentracing.GlobalTracer().Extract(
117 opentracing.HTTPHeaders,
118 opentracing.HTTPHeadersCarrier(req.Header))
119 if err != nil {
120 // Optionally record something about err here
121 }
122
123 // Create the span referring to the RPC client if available.
124 // If wireContext == nil, a root span will be created.
125 serverSpan = opentracing.StartSpan(
126 appSpecificOperationName,
127 ext.RPCServerOption(wireContext))
128
129 defer serverSpan.Finish()
130
131 ctx := opentracing.ContextWithSpan(context.Background(), serverSpan)
132 ...
133 }
134```
135
136#### Goroutine-safety
137
138The entire public API is goroutine-safe and does not require external
139synchronization.
140
141## API pointers for those implementing a tracing system
142
143Tracing system implementors may be able to reuse or copy-paste-modify the `basictracer` package, found [here](https://github.com/opentracing/basictracer-go). In particular, see `basictracer.New(...)`.
144
145## API compatibility
146
147For the time being, "mild" backwards-incompatible changes may be made without changing the major version number. As OpenTracing and `opentracing-go` mature, backwards compatibility will become more of a priority.
148
){kind=link}
){kind=link}
){kind=link}