This package is a Go platform API for OpenTracing.
In order to understand the Go platform API, one must first be familiar with the OpenTracing project and terminology more generally.
Everyday consumers of this opentracing
package really only need to worry
about a couple of key abstractions: the StartTrace
function, the Span
interface, and binding a Tracer
at main()
-time. Here are code snippets
demonstrating some important use cases.
The simplest starting point is ./default_tracer.go
. As early as possible, call
import ".../opentracing-go"
import ".../some_tracing_impl"
func main() {
tracerImpl := some_tracing_impl.New(...) // tracing impl specific
opentracing.InitGlobalTracer(tracerImpl)
...
}
If you prefer direct control to singletons, manage ownership of the
opentracing.Tracer
implementation explicitly.
func xyz() {
...
sp := opentracing.StartTrace("span_name")
defer sp.Finish()
sp.LogEvent("xyz_called")
...
}
func xyz(parentSpan opentracing.Span, ...) {
...
sp := opentracing.JoinTrace("span_name", parentSpan)
defer sp.Finish()
sp.LogEvent("xyz_called")
...
}
Additionally, this example demonstrates how to get a context.Context
associated with any opentracing.Span
instance.
func xyz(goCtx context.Context, ...) {
...
goCtx, sp := opentracing.ContextWithSpan(
goCtx, opentracing.JoinTrace("span_name", goCtx))
defer sp.Finish()
sp.LogEvent("xyz_called")
...
}
func makeSomeRequest(ctx context.Context) ... {
if span := opentracing.SpanFromContext(ctx); span != nil {
httpClient := &http.Client{}
httpReq, _ := http.NewRequest("GET", "http://myservice/", nil)
// Transmit the span's TraceContext as an HTTP header on our
// outbound request.
opentracing.GlobalTracer().PropagateSpanInHeader(
span,
httpReq.Header,
opentracing.DefaultTracer())
resp, err := httpClient.Do(httpReq)
...
}
...
}
http.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
// Join the trace in the HTTP header using the opentracing helper.
serverSpan, err := opentracing.GlobalTracer().JoinTraceFromHeader(
"serverSpan", req.Header, opentracing.GlobalTracer())
if err != nil {
serverSpan = opentracing.StartTrace("serverSpan")
}
var goCtx context.Context = ...
goCtx, _ = opentracing.ContextWithSpan(goCtx, serverSpan)
defer serverSpan.Finish()
...
}
The entire public API is goroutine-safe and does not require external synchronization.
Tracing system implementors may be able to reuse or copy-paste-modify the basictracer
package, found here. In particular, see basictracer.New(...)
.
For 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.