Migrate to Go Tracer v2

Docs > APM > Application Instrumentation > Custom Instrumentation > Go > Migrate to Go Tracer v2

Overview

The Go tracer v2 is a significant update to Datadog’s Go tracing library that introduces API improvements, better performance, and enhanced compatibility with modern Go practices. It represents the latest stable version of Datadog’s Go tracing library.

Compatibility

When deciding which version of the Go tracer to use, consider the following guidance:

For new projects: Datadog recommends using v2 for all new projects.
For Existing Projects: Datadog recommends migrating existing applications from v1 to take advantage of improvements and continued support.

Support policy

While v1 remains available, v2 is Datadog’s primary supported version:

Bug fixes for v1 will be provided until June 30, 2025
Security fixes for v1 will be provided until December 31, 2025
After December 31, 2025, v1 will no longer receive updates

For more compatibility and support details, see Go Library Compatibility.

Product-specific changes

Different Datadog products have specific considerations when migrating from v1 to v2. Here is what you need to know for each.

Application Security Management (ASM)

Supported packages have changed between v1 and v2 of the Go tracer.

For more information, see ASM language and framework compatibility.

Software Composition Analysis (SCA)

Supported packages have changed between v1 and v2 of the Go tracer.

For more information, see SCA language and framework compatibility.

Tracing

The v2 tracing API offers significant improvements while maintaining a similar developer experience. The migration typically involves updating import paths and adapting to some API changes.

Supported frameworks have changed between v1 and v2 of the Go tracer.

For more information, see Go Library Compatibility.

Profiling

For the Profiler, only import paths need to be updated. The profiling API functionality remains the same between v1 and v2.

Version 2 improvements

The Go tracer v2 introduces several important improvements:

Modern import path: Moves from gopkg.in to the standard GitHub import path for better compatibility with Go modules.
Improved API design: Provides a more intuitive interface with better performance and future extensibility.
Reduced dependency footprint: Isolates integrations so you only pull in what you need.
Enhanced security: Prevents false positives in security scanning tools.
Better OpenTelemetry compatibility: Includes W3C trace context propagation and 128-bit trace ID support.

Migration instructions

Datadog provides a migration tool that automatically handles most code updates when upgrading from v1 to v2.

To upgrade, run the following command:

go install github.com/DataDog/dd-trace-go/tools/v2check@latest
# In your repository's directory
v2check .

The tool makes the following changes:

Updates import URLs from gopkg.in/DataDog/dd-trace-go.v1 to github.com/DataDog/dd-trace-go/v2.
Moves imports from ddtrace/tracer to ddtrace where appropriate.
Converts Span and SpanContext calls to use pointers.
Replaces unsupported WithServiceName() calls with WithService().
Updates TraceID() calls to TraceIDLower() for obtaining uint64 trace IDs.

Troubleshooting

Import path changes

Change all imports from:

import "gopkg.in/DataDog/dd-trace-go.v1/ddtrace"
import "gopkg.in/DataDog/dd-trace-go.v1/profiler"

To:

import "github.com/DataDog/dd-trace-go/v2/ddtrace"
import "github.com/DataDog/dd-trace-go/v2/profiler"

Package structure changes

The package organization has changed in v2. Many functions previously in ddtrace/tracer have been moved to the ddtrace package. While the v2check migration tool handles these changes automatically, you may need to manually update some import paths.

v1:

import "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"

func main() {
    tracer.Start()
    span := tracer.StartSpan("operation")
}

v2:

import "github.com/DataDog/dd-trace-go/v2/ddtrace"

func main() {
    ddtrace.Start()
    span := ddtrace.StartSpan("operation")
}

Configuration changes

The WithServiceName() option has been replaced with WithService() for consistency:

// v1
tracer.Start(tracer.WithServiceName("my-service"))

// v2
ddtrace.Start(ddtrace.WithService("my-service"))

For more information, see the godoc page for dd-trace-go v2.