Migration Guide

This document outlines migrating from an older version of the Datadog tracer (0.6.x) to v1.

Datadog's v1 version of the Go tracer provides not only an overhauled core that comes with huge performance improvements, but also the promise of a new and stable API to be relied on. It is the result of continuous feedback from customers, the community, as well as our extensive internal usage.

As is common and recommended in the Go community, the best way to approach migrating to this new API is by using the gradual code repair method. We have done the same internally and it has worked just great! For this exact reason we have provided a new, semver friendly import path to help with using both tracers in parallel, without conflict, for the duration of the migration. This new path is gopkg.in/DataDog/dd-trace-go.v1.

Our godoc page should deem helpful during this process. We also have the official documentation, which contains a couple of examples.

This document will further outline some before and after examples.

Starting the tracer

The new tracer needs to be started before it can be used. A default started tracer is no longer available. The default tracer is now a no-op.

Here is an example of starting a custom tracer with a non-default agent endpoint using the old API:

t := tracer.NewTracerTransport(tracer.NewTransport("localhost", "8199"))
t.SetDebugLogging(true)
defer t.ForceFlush()

This would now become:

tracer.Start(
    tracer.WithAgentAddr("localhost:8199"),
    tracer.WithDebugMode(true),
)
defer tracer.Stop()

Notice that the tracer object is no longer returned. Consult the documentation to see all possible parameters to the Start call.

Service Information

The tracer.SetServiceInfo method has been deprecated. The service information is now set automatically based on the value of the ext.SpanType tag that was set on the root span of a trace.

Spans

Starting spans is now possible with functional options. Which means that all span properties (or none) can be set when starting a span dynamically. Before:

span := tracer.NewRootSpan("web.request", "my_service", "resource_name")

Becomes:

span := tracer.StartSpan("web.request", tracer.ServiceName("my_service"), tracer.ResourceName("resource_name"))

We've done this because in many cases the extra parameters could become tedious, given that service names can be inherited and resource names can default to the operation name. This also allows us to have one single, more dynamic API for starting both root and child spans. Check out all possible StartSpanOption values to get an idea.

Children

Here is an example for spawning a child of the previously declared span:

child := tracer.StartSpan("process.user", tracer.ChildOf(span.Context()))

You will notice that the new tracer also introduces the concept of SpanContext, which is different from Go's context and is used to carry information needed to spawn children of a specific span and can be propagated cross-process. To learn more about distributed tracing check the package-level documentation of the tracer package.

Using Go's context

It is also possible to create children of spans that live inside Go's context:

child, ctx := tracer.StartSpanFromContext(ctx, "process.user", tracer.Tag("key", "value"))

This will create a child of the span which exists inside the passed context and return it, along with a new context which contains the new span. To add or retrieve a span from a context use the ContextWithSpan or SpanFromContext functions.

Setting errors

The SetError has been deprecated in favour of the ext.Error tag value which matches other tracing libraries in the wild. Whereas before we had:

span.SetError(err)

Now we have:

span.SetTag(ext.Error, err)

Note that this tag can accept value of the types error, string and bool as well for setting errors.

Finishing

The FinishWithErr and FinishWithTime methods have been removed in favour of a set of FinishOption. For example, this would now become:

span.Finish(tracer.WithError(err), tracer.FinishTime(t))

Providing a nil value as an error is perfectly fine and will not mark the span as erroneous.

5.9 KiB Raw Blame History