Go 애플리케이션 트레이싱 (Tracing Go Applications)
Go 애플리케이션에 dd-trace-go를 사용해 트레이스를 Datadog으로 보내는 방법이에요. 컴파일 타임 계측(Orchestrion)과 수동 계측 두 가지 방식을 다룹니다.
출처: 문서
본문
호환성 요구사항 (Compatibility requirements)
Go 트레이서는 Go 1.18+와 Datadog Agent >= 5.21.1이 필요해요. Datadog의 Go 버전·프레임워크 지원(레거시·유지보수 버전 포함) 전체 목록은 호환성 요구사항 페이지를 참고하세요.
참고: 이 문서는 Go 트레이서 v2를 사용해요. Datadog은 모든 사용자에게 v2를 권장해요. v1을 사용 중이라면 마이그레이션 가이드를 참고해 v2로 업그레이드하세요.
시작하기 (Getting started)
시작하기 전에 Agent를 이미 설치·구성했는지 확인하세요.
Go 애플리케이션을 계측하는 방법은 두 가지가 있어요.
-
컴파일 타임 계측 (Compile-time instrumentation):
- 트레이싱 계측 범위를 최대화해요.
- 소스 코드 수정이 필요 없어 CI/CD 수준에서 통합하기에 이상적이에요.
-
수동 계측 (Manual instrumentation):
dd-trace-go를 통합 패키지와 함께 사용해 선택한 라이브러리에 대한 스팬을 자동으로 생성할 수 있어요. 이 옵션은:
- 애플리케이션의 어느 부분을 트레이싱할지 완전히 제어할 수 있어요.
- 애플리케이션의 소스 코드를 수정해야 해요.
아래에서 선호하는 방식에 해당하는 섹션의 지침을 참고하세요.
컴파일 타임 계측 (Compile-time instrumentation)
개요 (Overview)
Orchestrion은 컴파일 중에 Go 애플리케이션에 계측을 자동으로 추가해 줘요. 그래서 코드 변경이 필요 없어요. 포괄적인 트레이싱 범위를 제공하고 독점 보안 기능을 활성화해요.
- 포괄적인 트레이싱 범위:
- 코드와 Go 표준 라이브러리를 포함한 모든 의존성을 계측해요.
- 컴파일 중에 코드를 계측해서, 놓친 수동 계측으로 인한 트레이싱 공백을 방지해요.
- 독점 App and API Protection의 Exploit Prevention 기능. Exploit Prevention은 RASP(Runtime Application Self-Protection) 구현이며 LFI(Local File Inclusion) 같은 RASP 메서드를 포함해요.
요구사항 (Requirements)
- 최신 두 개의 Go 런타임 릴리스를 지원해요(Go 공식 릴리스 정책과 일치).
- 애플리케이션은 go modules로 관리해야 해요. 모듈 벤더링도 지원돼요.
Orchestrion 설치 (Install Orchestrion)
Orchestrion을 설치·설정하려면:
-
Orchestrion을 설치하세요.
go install github.com/DataDog/orchestrion@latest$(go env GOBIN)또는$(go env GOPATH)/bin이$PATH에 있는지 확인하세요. -
프로젝트의
go.mod에 Orchestrion을 등록하세요.orchestrion pin사용 가능한 사용자 지정 옵션에 대한 자세한 내용은
orchestrion pin -help출력을 참고하세요. -
변경 사항을 버전 관리 시스템에 커밋하세요(CI/CD 파이프라인에
orchestrion을 직접 통합하지 않는 경우).git add go.mod go.sum orchestrion.tool.go git commit -m "chore: enable orchestrion"
이제 go.mod 파일을 통해 다른 의존성처럼 orchestrion 의존성을 관리할 수 있어요.
사용법 (Usage)
빌드 프로세스에서 Orchestrion을 활성화하려면 다음 방법 중 하나를 사용하세요.
평소 go 명령 앞에 orchestrion을 붙이기
orchestrion go build .
orchestrion go run .
orchestrion go test ./...
go 명령에 -toolexec="orchestrion toolexec" 인자 추가하기
go build -toolexec="orchestrion toolexec" .
go run -toolexec="orchestrion toolexec" .
go test -toolexec="orchestrion toolexec" ./...
$GOFLAGS 환경 변수로 Orchestrion 주입하고 go 명령을 평소처럼 사용하기
# 아래처럼 따옴표를 반드시 포함해야 해요. Go 툴체인이 GOFLAGS를 올바르게 파싱하려면 필요해요!
export GOFLAGS="${GOFLAGS} '-toolexec=orchestrion toolexec'"
go build .
go run .
go test ./...
트레이스 사용자 지정 (Trace Customization)
Unified Service Tagging 설정하기
orchestrion으로 계측된 애플리케이션은 Unified Service Tagging(UST)을 지원해요. 애플리케이션의 런타임 환경에 해당 환경 변수를 설정해 트레이스에 UST 태그를 지정할 수 있어요.
| Unified 태그 | 환경 변수 |
|---|---|
env |
DD_ENV |
service |
DD_SERVICE |
version |
DD_VERSION |
자세한 내용은 Unified Service Tagging 문서를 참고하세요.
트레이서 구성
구성 지침은 라이브러리 구성을 참고하세요.
커스텀 트레이스 스팬 만들기
//dd:span 지시문 주석이 달린 모든 함수에 커스텀 트레이스 스팬이 자동으로 생성될 수 있어요.
example.go 파일에서:
//dd:span custom_tag:tag_value
func CriticalPathFunction() {
// ... 구현 세부 사항 ...
}
함수 리터럴 표현식에서도 동작해요.
example.go 파일에서:
//dd:span custom_tag:tag_value
handler := func(w http.ResponseWriter, r *http.Request) {
// ... 구현 세부 사항 ...
}
작업 이름 (Operation Name)
작업 이름(span.name)은 다음 우선순위로 자동 결정돼요.
- 지시문 인자로 지정된 명시적
span.name:customOperationName태그 - 함수의 선언된 이름(익명인 함수 리터럴 표현식에는 적용되지 않아요)
- 지시문 인자 목록에 제공된 첫 번째 태그의 값
example.go 파일에서:
//dd:span tag-name:spanName other-tag:bar span.name:operationName
func tracedFunction() {
// 이 함수는 "operationName"이라는 이름의 스팬으로 표현돼요
}
//dd:span tag-name:spanName other-tag:bar
func otherTracedFunction() {
// 이 함수는 "otherTracedFunction"이라는 이름의 스팬으로 표현돼요
}
//dd:span tag-name:spanName other-tag:bar
tracedFunction := func() {
// 이 함수는 "spanName"이라는 이름의 스팬으로 표현돼요
}
오류 결과 (Error Results)
주석이 달린 함수가 error 결과를 반환하면, 함수가 반환한 모든 오류가 해당 트레이스 스팬에 자동으로 첨부돼요.
example.go 파일에서:
//dd:span
func failableFunction() (any, error) {
// 이 스팬에는 오류 정보가 자동으로 첨부돼요.
return nil, errors.ErrUnsupported
}
일부 코드 계측 방지하기
//orchestrion:ignore 지시문을 사용해 orchestrion이 주석이 달린 코드에 대해 어떤 수정도 수행하지 못하게 할 수 있어요.
이 지시문은 호출자 측 계측이 특정 위치에 적용되는 것을 막는 데 사용할 수 있어요.
example.go 파일에서:
import "database/sql"
// 호출자 측 계측은 보통 이 함수 안에서 일어나요...
func normal() {
// 다음 할당은 orchestrion:ignore 지시문으로 옵트아웃되어
// 호출자 측 계측이 추가되지 않을 거예요:
//orchestrion:ignore
db, err := sql.Open("driver-name", "database=example")
// ...
}
// 다음 함수는 orchestrion:ignore로 주석이 달려
// 호출자 측 계측이 일어나지 않아요.
//orchestrion:ignore
func excluded() {
// 다음 할당은 주변 컨텍스트가 orchestrion:ignore
// 지시문으로 제외되어 호출자 측 계측이 추가되지 않아요:
db, err := sql.Open("driver-name", "database=example")
// ...
}
orchestrion이 수행하는 일부 계측은 callee-side(라이브러리 측)로 일어나는데, 즉 통합이 의존성 자체 안에 직접 추가돼요. 이 경우 해당 통합을 로컬에서 옵트아웃할 수 없어요.
SDK 사용하기
Orchestrion으로 빌드한 애플리케이션에서 SDK를 사용할 수 있어요. 이는 Orchestrion이 아직 지원하지 않는 프레임워크를 계측할 때 유용해요. 다만 Orchestrion 지원이 확장됨에 따라 트레이스 스팬이 중복될 수 있다는 점을 알아두세요. orchestrion 의존성을 업데이트할 때 릴리스 노트를 검토해 새 기능을 파악하고 수동 계측을 그에 맞게 조정하세요.
연속 프로파일러 사용하기
Orchestrion으로 빌드한 애플리케이션에는 continuous profiler 계측이 포함돼요. 프로파일러를 활성화하려면 런타임에 환경 변수 DD_PROFILING_ENABLED=true를 설정하세요.
통합 제거하기
orchestrion.tool.go 파일의 import를 수정해 통합을 제거할 수 있어요. 또한 orchestrion을 실행하기 전에 자신만의 orchestrion.tool.go 파일을 만들 수도 있어요. 통합을 원하지 않거나, 프로그램이 사용하지 않는 통합의 전이적 의존성 수를 줄이고 싶을 때 이렇게 할 수 있어요. 기본적으로 Orchestrion은 github.com/DataDog/dd-trace-go/orchestrion/all/v2를 import하는데, 이는 Orchestrion 통합이 있는 모든 라이브러리를 import해요. 이 import를 원하는 통합만으로 바꿀 수 있어요. 지원되는 통합 목록은 SDK 소스 코드를 참고하세요.
참고: 특정 통합만 import하기로 했다면, 새 통합을 추가할 때마다 orchestrion.tool.go를 수동으로 업데이트해야 해요.
Docker로 빌드하기
적합한 Docker 이미지를 만드는 방법은 Go용 APM Dockerfile 만들기를 참고하세요.
문제 해결 (Troubleshooting)
orchestrion이 관리하는 빌드를 문제 해결하려면 Go 컴파일 타임 계측 문제 해결을 참고하세요.
수동 계측 (Manual instrumentation)
SDK를 애플리케이션에 추가하기
먼저 라이브러리 구성 문서를 따라 코드에서 SDK를 import하고 시작하세요. 구성 지침과 API 사용 세부 정보는 API 문서(또는 v1 API 문서)를 참고하세요.
스팬을 만들도록 Go 통합 활성화하기
스팬을 생성하도록 Go 통합을 활성화하세요. Datadog은 다양한 라이브러리·프레임워크 계측을 기본 지원하는 플러그형 패키지 시리즈를 제공해요. 이 패키지 목록은 호환성 요구사항 페이지에서 확인할 수 있어요. 이 패키지들을 애플리케이션에 import하고 각 통합 옆에 나열된 구성 지침을 따르세요.
더 알아보기 (Learn more)
도움이 되는 추가 문서, 링크, 글: