Go 트레이서 v2로 마이그레이션 (Migrate to Go Tracer v2)

원문 보기 위키 갱신 2026.10.05

Go 트레이서를 v1에서 v2로 업그레이드하는 방법이에요. v2의 개선 사항, 지원 정책, 마이그레이션 도구와 주요 변경 사항을 다룹니다.

출처: 문서

본문

개요 (Overview)

Go 트레이서 v2는 API 개선, 더 나은 성능, 현대적인 Go 관행과의 향상된 호환성을 도입해요. Datadog Go SDK의 최신 안정 버전이에요.

호환성 (Compatibility)

어떤 Go 트레이서 버전을 사용할지 결정할 때는 다음 지침을 참고하세요.

새 프로젝트: Datadog은 모든 새 프로젝트에 v2 사용을 권장해요.
기존 프로젝트: Datadog은 개선 사항과 지속적 지원을 활용하기 위해 기존 애플리케이션을 v2로 마이그레이션하는 것을 권장해요.

지원 정책 (Support policy)

v1이 계속 제공되지만 v2가 Datadog의 기본 지원 버전이에요. v1.74.0부터 시작하는 모든 v1 릴리스에는 새 기능이 포함되지 않고 대신 전환(transitional) 릴리스로 간주돼요. 이 릴리스들은 내부적으로 v2를 사용하면서 v1 API를 유지해요. 전환 v1 버전을 v2와 함께 사용하면 서비스를 점진적으로 마이그레이션할 수 있어요.

호환성·지원 세부 정보는 Go 라이브러리 호환성을 참고하세요.

제품별 변경 사항 (Product-specific changes)

각 Datadog 제품마다 v1에서 v2로 마이그레이션할 때 고려할 사항이 있어요.

트레이싱 (Tracing)

v2 트레이싱 API는 비슷한 개발자 경험을 유지하면서 상당한 개선을 제공해요. 마이그레이션은 보통 import 경로를 업데이트하고 일부 API 변경에 적응하는 것이 포함돼요.

지원되는 프레임워크가 Go 트레이서 v1과 v2 사이에서 변경됐어요.

자세한 내용은 Go 라이브러리 호환성을 참고하세요.

프로파일링 (Profiling)

프로파일러는 import 경로만 업데이트하면 돼요. 프로파일링 API 기능은 v1과 v2 사이에서 동일해요.

App and API Protection (AAP)

지원되는 패키지가 Go 트레이서 v1과 v2 사이에서 변경됐어요.

자세한 내용은 AAP 언어·프레임워크 호환성을 참고하세요.

Software Composition Analysis (SCA)

import 경로만 업데이트하면 돼요. SCA의 프레임워크 지원은 v1과 v2 사이에서 동일해요.

버전 2 개선 사항 (Version 2 improvements)

Go 트레이서 v2는 몇 가지 중요한 개선을 도입해요.

현대적인 import 경로: gopkg.in에서 표준 GitHub import 경로로 이동해 Go 모듈과의 호환성을 높여요.
개선된 API 설계: 더 나은 성능과 미래 확장성을 지닌 더 직관적인 인터페이스를 제공해요.
줄어든 의존성 범위: 통합을 분리해서 필요한 것만 가져올 수 있어요.
향상된 보안: 보안 스캔 도구에서 오탐을 방지해요.
더 나은 OpenTelemetry 호환성: W3C 트레이스 컨텍스트 전파와 128비트 트레이스 ID 지원을 포함해요.

마이그레이션 지침 (Migration instructions)

Datadog은 v1에서 v2로 업그레이드할 때 대부분의 코드 업데이트를 자동으로 처리하는 마이그레이션 도구를 제공해요.

업데이트를 확인하려면 다음 명령을 실행하세요.

go install github.com/DataDog/dd-trace-go/tools/v2fix@latest
# 저장소 디렉터리에서
v2fix .

제안된 모든 수정을 적용하려면 다음을 실행하세요.

v2fix -fix .

이 도구는 다음 변경을 수행해요.

import URL을 gopkg.in/DataDog/dd-trace-go.v1에서 github.com/DataDog/dd-trace-go/v2로 업데이트해요.
적절한 곳에서 ddtrace에서 ddtrace/tracer로 import를 이동해요.
Span과 SpanContext 호출을 구체 값 사용으로 변환해요.
지원되지 않는 WithServiceName 호출을 WithService로 교체해요.
uint64 트레이스 ID를 얻기 위해 TraceID 호출을 TraceIDLower로 업데이트해요.

주요 변경 사항 (Breaking changes)

import 경로 변경 (Import path changes)

모든 import를 다음과 같이 변경하세요.

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

다음으로:

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

패키지 구조 변경 (Package structure changes)

패키지 구성이 v2에서 변경됐어요. 이전에 ddtrace에 있던 많은 함수가 ddtrace/tracer 패키지로 이동했어요. v2fix 마이그레이션 도구가 이런 변경을 자동으로 처리하지만, 일부 import 경로는 수동으로 업데이트해야 할 수 있어요.

v1:

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

func main() {
    tracer.Start()
	  defer tracer.Stop()

	  s := tracer.StartSpan("op")
	  var ctx ddtrace.SpanContext = s.Context()
}

v2:

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

func main() {
    tracer.Start()
	  defer tracer.Stop()

	  s := tracer.StartSpan("op")
	  var ctx *tracer.SpanContext = s.Context()
}

API 변경 (API changes)

API 개선으로 일부 함수와 타입이 변경됐어요. 자세한 내용은 dd-trace-go v2 godoc 페이지를 참고하세요.

스팬 (Spans)

Span과 SpanContext가 이제 인터페이스가 아닌 구조체로 표현돼요. 따라서 이 타입에 대한 참조는 포인터를 사용해야 해요. 또한 tracer 패키지 안으로 이동했으므로 ddtrace.Span이 아니라 tracer.Span으로 접근해야 해요.

v1:

var sp ddtrace.Span = tracer.StartSpan("opname")
var ctx ddtrace.SpanContext = sp.Context()

v2:

var sp *tracer.Span = tracer.StartSpan("opname")
var ctx *tracer.SpanContext = sp.Context()

사용되지 않는 ddtrace 인터페이스

ddtrace의 모든 인터페이스가 구조체 타입을 위해 제거됐어요. 새 타입은 ddtrace/tracer로 이동했어요.

사용되지 않는 상수와 옵션

다음 상수와 함수가 제거됐어요.

ddtrace/ext.AppTypeWeb
ddtrace/ext.CassandraQuery
ddtrace/ext.CassandraBatch
ddtrace/tracer.WithPrioritySampling; 우선순위 샘플링은 기본적으로 활성화돼요.
ddtrace/tracer.WithHTTPRoundTripper; 대신 WithHTTPClient를 사용하세요.

StartChild

자식 스팬은 ChildOf가 아니라 StartChild로 시작해요.

v1:

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

func main() {
  tracer.Start()
	defer tracer.Stop()

	parent := tracer.StartSpan("op").Context()
	child := tracer.StartSpan("op", tracer.ChildOf(parent))
}

v2:

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

func main() {
  tracer.Start()
	defer tracer.Stop()

	parent := tracer.StartSpan("op")
	child := parent.StartChild("op")
}

트레이스 ID (Trace IDs)

uint64가 아니라 트레이스 ID가 이제 string으로 표현돼요. 이 변경으로 128비트 트레이스 ID를 지원할 수 있게 됐어요. 새 TraceIDLower() 메서드를 사용해 이전 동작에 계속 접근할 수 있지만, 128비트 ID로 전환하는 것이 권장돼요.

v1:

sp := tracer.StartSpan("opname")
fmt.Printf("traceID: %d\n", sp.Context().TraceID())

v2:

sp := tracer.StartSpan("opname")
fmt.Printf("traceID: %s\n", sp.Context().TraceID()) //128비트 ID 사용에 권장
fmt.Printf("traceID: %d\n", sp.Context().TraceIDLower()) // 64비트 ID로 이전 동작 유지

Span Links API

Span.AddSpanLink가 Span.AddLink로 이름이 바뀌었어요.

구성 변경 (Configuration changes)

WithService

일관성을 위해 WithServiceName 옵션이 WithService로 교체됐어요.

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

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

WithDogstatsdAddress

tracer.WithDogstatsdAddress가 tracer.WithDogstatsdAddr로 이름이 바뀌었어요. SDK를 시작할 때 다른 DogStatsD 주소를 지정하는 데 이 옵션을 사용하세요.

v1:

tracer.Start(tracer.WithDogstatsdAddress("10.1.0.12:4002"))

v2:

tracer.Start(tracer.WithDogstatsdAddr("10.1.0.12:4002"))

WithAgentURL

tracer.WithAgentURL은 기존 WithAgentAddr 옵션에 더해 에이전트가 있는 URL 주소를 설정해요. 에이전트가 Unix Domain Socket에서 수신 대기하는 설정에 유용해요.

v2:

tracer.Start(tracer.WithAgentURL("unix:///var/run/datadog/apm.socket"))

NewStartSpanConfig, WithStartSpanConfig, WithFinishConfig

ddtrace/tracer.Tracer.StartSpan과 ddtrace/tracer.Span.Finish를 위한 이 함수형 옵션들은 핫 루프에서 호출 수(함수형 옵션 형태)를 줄여줘요. 핫 경로에서 공통 스팬 구성을 준비할 자유를 주죠.

v1:

var err error
span := tracer.StartSpan(
	"operation",
	ChildOf(parent.Context()),
	Measured(),
	ResourceName("resource"),
	ServiceName(service),
	SpanType(ext.SpanTypeWeb),
	Tag("key", "value"),
)
defer span.Finish(tracer.NoDebugStack())

v2:

cfg := tracer.NewStartSpanConfig(
	tracer.Measured(),
	tracer.ResourceName("resource"),
	tracer.ServiceName(service),
	tracer.SpanType(ext.SpanTypeWeb),
	tracer.Tag("key", "value"),
)
finishCfg := tracer.NewFinishConfig(
	NoDebugStack(),
)
// [...]
// 핫 경로에서 구성을 재사용하세요:
span := parent.StartChild("operation", tracer.WithStartSpanConfig(cfg))
defer span.Finish(tracer.WithFinishConfig(finishCfg))

샘플링 API 단순화 (Sampling API simplified)

SpanSamplingRules와 TraceSamplingRules를 위해 다음 함수가 제거됐어요.

NameRule
NameServiceRule
RateRule
ServiceRule
SpanNameServiceMPSRule
SpanNameServiceRule
SpanTagsResourceRule
TagsResourceRule

또한 ext.SamplingPriority 태그는 사용되지 않아요. 대신 ext.ManualKeep와 ext.ManualDrop을 사용하세요.

더 알아보기 (Learn more)

Go 커스텀 계측