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() {
            // tracing impl specific:

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 for Span propagation. To start a new (blocking child) Span, you can use StartSpanFromContext.

    func xyz(ctx context.Context, ...) {
        span, ctx := opentracing.StartSpanFromContext(ctx, "operation_name")
        defer span.Finish()
            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) Span

    func xyz(parentSpan opentracing.Span, ...) {
        sp := opentracing.StartSpan(
        defer sp.Finish()

Serializing to the wire

    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.

            resp, err := httpClient.Do(httpReq)

Deserializing from the wire

    http.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
        var serverSpan opentracing.Span
        appSpecificOperationName := ...
        wireContext, err := opentracing.GlobalTracer().Extract(
        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(

        defer serverSpan.Finish()

        ctx := opentracing.ContextWithSpan(context.Background(), serverSpan)

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()