Project: OpenTracing (Observability and Analysis / Observability)
File: README.md

](https://gitter.im/opentracing/public) ](https://travis-ci.org/opentracing/opentracing-go) ](http://godoc.org/github.com/opentracing/opentracing-go) ](https://sourcegraph.com/github.com/opentracing/opentracing-go?badge) This package is a Go platform API for OpenTracing. In order to understand the Go platform API, one must first be familiar with the and more specifically. 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. The simplest starting point is `./default_tracer.go`. As early as possible, call ```go import "github.com/opentracing/opentracing-go" import ".../sometracingimpl" func main() { opentracing.SetGlobalTracer( // tracing impl specific: sometracingimpl.New(...), ) ... } ``` If you prefer direct control to singletons, manage ownership of the `opentracing.Tracer` implementation explicitly. If you use `context.Context` in your application, OpenTracing's Go library will happily rely on it for `Span` propagation. To start a new (blocking child) `Span`, you can use `StartSpanFromContext`. ```go 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)) ... } ``` It's always possible to create a "root" `Span` with no parent or other causal reference. ```go func xyz() { ... sp := opentracing.StartSpan("operation_name") defer sp.Finish() ... } ``` ```go func xyz(parentSpan opentracing.Span, ...) { ... sp := opentracing.StartSpan( "operation_name", opentracing.ChildOf(parentSpan.Context())) defer sp.Finish() ... } ``` ```go 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 HTTP headers on our // outbound request. opentracing.GlobalTracer().Inject( span.Context(), opentracing.HTTPHeaders, opentracing.HTTPHeadersCarrier(httpReq.Header)) resp, err := httpClient.Do(httpReq) ... } ... } ``` ```go 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) ... } ``` 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: ```go func Customer(order *Order) log.Field { if os.Getenv("ENVIRONMENT") == "dev" { return log.String("customer", order.Customer.ID) } return log.Noop() } ``` 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 . 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. A test suite is available in the package that can assist Tracer implementors to assert that their Tracer is working correctly. .