OpenTracing API for Go. 🛑 This library is DEPRECATED! https://github.com/opentracing/specification/issues/163
This package is a Go platform API for OpenTracing.
Required Reading
In order to understand the Go platform API, one must first be familiar with the OpenTracing project and terminology more specifically.
API overview for those adding instrumentation
Everyday consumers of this opentracing
package really only need to worry
about a couple of key abstractions: the StartSpan
function, the Span
interface, and binding a Tracer
at main()
-time. Here are code snippets
demonstrating some important use cases.
Singleton initialization
The simplest starting point is ./default_tracer.go
. As early as possible, call
import "github.com/opentracing/opentracing-go" import ".../some_tracing_impl"func main() { opentracing.SetGlobalTracer( // tracing impl specific: some_tracing_impl.New(...), ) ... }</pre>
Non-Singleton initialization
If you prefer direct control to singletons, manage ownership of the
opentracing.Tracer
implementation explicitly.Creating a Span given an existing Go
context.Context
If you use
context.Context
in your application, OpenTracing's Go library will happily rely on it forSpan
propagation. To start a new (blocking child)Span
, you can useStartSpanFromContext
.func xyz(ctx context.Context, ...) { ... span, ctx := opentracing.StartSpanFromContext(ctx, "operation_name") defer span.Finish() span.LogFields( log.String("event", "soft error"), log.String("type", "cache timeout"), log.Int("waited.millis", 1500)) ... }Starting an empty trace by creating a "root span"It's always possible to create a "root"
Span
with no parent or other causal reference.func xyz() { ... sp := opentracing.StartSpan("operation_name") defer sp.Finish() ... }Creating a (child) Span given an existing (parent) Spanfunc xyz(parentSpan opentracing.Span, ...) { ... sp := opentracing.StartSpan( "operation_name", opentracing.ChildOf(parentSpan.Context())) defer sp.Finish() ... }Serializing to the wirefunc 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 HTTP headers on our // outbound request. opentracing.GlobalTracer().Inject( span.Context(), opentracing.HTTPHeaders, opentracing.HTTPHeadersCarrier(httpReq.Header)) resp, err := httpClient.Do(httpReq) ... } ... }</pre>
Deserializing from the wire
http.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) { var serverSpan opentracing.Span appSpecificOperationName := ... wireContext, err := opentracing.GlobalTracer().Extract( opentracing.HTTPHeaders, opentracing.HTTPHeadersCarrier(req.Header)) if err != nil { // Optionally record something about err here }// Create the span referring to the RPC client if available. // If wireContext == nil, a root span will be created. serverSpan = opentracing.StartSpan( appSpecificOperationName, ext.RPCServerOption(wireContext)) defer serverSpan.Finish() ctx := opentracing.ContextWithSpan(context.Background(), serverSpan) ... }</pre>
Conditionally capture a field using
log.Noop
In some situations, you may want to dynamically decide whether or not to log a field. For example, you may want to capture additional data, such as a customer ID, in non-production environments:
func Customer(order *Order) log.Field { if os.Getenv("ENVIRONMENT") == "dev" { return log.String("customer", order.Customer.ID) } return log.Noop() }Goroutine-safetyThe entire public API is goroutine-safe and does not require external synchronization.
API pointers for those implementing a tracing system
Tracing system implementors may be able to reuse or copy-paste-modify the
basictracer
package, found here. In particular, seebasictracer.New(...)
.API compatibility
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.Tracer test suite
A test suite is available in the harness package that can assist Tracer implementors to assert that their Tracer is working correctly.
Licensing
Twice a month we will interview people behind open source businesses. We will talk about how they are building a business on top of open source projects.
We'll never share your email with anyone else.