개요

Orchestrion은 컴파일 중에 Go 애플리케이션에 자동으로 계측을 추가하여 코드를 변경할 필요가 없습니다. 이렇게 하면 포괄적인 트레이싱 커버리지가 제공되고 독점 보안 기능이 활성화됩니다.

• 포괄적인 트레이싱 커버리지:
  • Go 표준 라이브러리를 포함해 코드 및 모든 종속성 계측
  • 컴파일 중에 코드를 계측하여 간과된 수동 계측으로 인한 트레이싱 커버리지 빈틈 방지
• 독점적 App and API Protection Exploit Prevention 기능. Exploit Prevention은 Runtime Application Self-Protection(RASP) 구현이며 Local File Inclusion(LFI)과 같은 RASP 방법을 포함합니다.

요구 사항

• 최신 Go 런타임 릴리스 두 개를 지원합니다(Go의 공식 릴리스 정책과 일치).
• 애플리케이션을 go 모듈을 사용하여 관리해야 합니다. 모듈 벤더링이 지원됩니다.

Orchestrion 설치

Orchestrion을 설치하고 설정하는 방법:

1. Orchestrion 설치:

   go install github.com/DataDog/orchestrion@latest
   

   $(go env GOBIN) 또는 $(go env GOPATH)/bin 이 $PATH에 있어야 합니다.

2. 프로젝트의 go.mod에 Orchestrion 등록:

   orchestrion pin
   

   사용 가능한 사용자 지정 옵션에 관한 자세한 정보는 orchestrion pin -help 출력을 참조하세요.

3. 버전 관리 시스템에 변경 사항 커밋(단, orchestrion을 CI/CD 파이프라인에 직접 통합하는 경우는 예외):

   git add go.mod go.sum orchestrion.tool.go
   git commit -m "chore: enable orchestrion"
   

   이제 orchestrion에서 다른 모든 종속성과 마찬가지로 go.mod 파일을 사용하여 종속성을 관리할 수 있습니다.

사용량

다음 중 한 가지 방법을 사용하여 빌드 프로세스에서 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 명령 사용:

# Make sure to include the quotes as shown below, as these are required for
# the Go toolchain to parse GOFLAGS properly!
export GOFLAGS="${GOFLAGS} '-toolexec=orchestrion toolexec'"
go build .
go run .
go test ./...

트레이스 사용자 지정

Unified Service Tagging 설정

orchestrion으로 계측한 애플리케이션은 Unified Service Tagging(UST)을 지원합니다. 애플리케이션의 런타임 환경에서 해당하는 환경 변수를 설정하여 트레이스에 UST 태그를 설정할 수 있습니다.

자세한 내용은 Unified Service Tagging 설명서를 참조하세요.

트레이서 구성

구성 지침은 라이브러리 구성을 참조하세요.

사용자 지정 트레이스 스팬 생성

사용자 지정 트레이스 스팬은 //dd:span 지시문 코멘트로 어노테이션된 모든 함수에 대하여 자동으로 생성할 수 있습니다.

//dd:span custom_tag:tag_value
func CriticalPathFunction() {
  // ... implementation details ...
}

이것은 함수 리터럴 표현식에도 사용할 수 있습니다.

//dd:span custom_tag:tag_value
handler := func(w http.ResponseWriter, r *http.Request) {
  // ... implementation details ...
}

작업 이름

작업의 이름(span.name)은 다음 우선순위를 사용하여 자동으로 결정됩니다.

1. 지시문 인수로 지정된 명시적 span.name:customOperationName 태그
2. 함수의 선언된 이름(이것은 함수 리터럴 표현식(익명)에는 해당하지 않음)
3. 지시문 인수 목록에 제공된 첫 번째 태그의 값

//dd:span tag-name:spanName other-tag:bar span.name:operationName
func tracedFunction() {
  // This function will be represented as a span named "operationName"
}

//dd:span tag-name:spanName other-tag:bar
func otherTracedFunction() {
  // This function will be represented as a span named "otherTracedFunction"
}

//dd:span tag-name:spanName other-tag:bar
tracedFunction := func() {
  // This function will be represented as a span named "spanName"
}

오류 결과

어노테이션된 함수가 error 결과를 반환하는 경우, 해당 함수가 반환한 모든 오류가 자동으로 상응하는 트레이스 스팬에 연결됩니다.

//dd:span
func failableFunction() (any, error) {
  // This span will have error information attached automatically.
  return nil, errors.ErrUnsupported
}

일부 코드의 계측 방지

//orchestrion:ignore 지시문을 사용하여 orchestrion이 어노테이션된 코드에서 아무런 수정도 수행하지 못하도록 방지할 수 있습니다.

이렇게 하면 호출자 측 계측이 특정 위치에 적용되지 않도록 방지할 수 있습니다.

import "database/sql"

// Caller-side instrumentation normally happens within this function...
func normal() {
  // The following assignment will NOT be modified to add any caller-side
  // instrumentation as it is opted out by the orchestrion:ignore directive:
  //orchestrion:ignore
  db, err := sql.Open("driver-name", "database=example")
  // ...
}

// Caller-side instrumentation will NOT happen in the following function
// as it is annotated with orchestrion:ignore.
//orchestrion:ignore
func excluded() {
  // The following assignment will NOT be modified to add any caller-side
  // instrumentation as the surrounding context is excluded by an
  // orchestrion:ignore directive:
  db, err := sql.Open("driver-name", "database=example")
  // ...
}

orchestrion이 수행하는 계측 중 일부는 피호출자 측(또는 라이브러리 측)에서 수행되는데, 이는 통합이 종속성 자체 내에 직접 추가된다는 의미입니다. 이런 경우에는 해당 통합에서 로컬로 옵트아웃할 수 없습니다.

SDK 사용

Orchestrion으로 빌드한 애플리케이션에서 SDK를 사용할 수 있습니다. 이것은 Orchestrion으로 아직 지원되지 않는 프레임워크를 계측하는 데 유용합니다. 단, 이렇게 하면 Orchestrion 지원이 확장됨에 따라 향후 트레이스 스팬이 중복될 가능성이 있다는 점을 유의해야 합니다. orchestrion 종속성을 업데이트할 때 릴리스 노트를 검토하여 새 기능에 관한 최신 정보를 접하고 필요에 따라 수동 계측을 조정하세요.

Continuous Profiler 사용

Orchestrion으로 빌드한 애플리케이션에는 Continuous Profiler 계측이 포함되어 있습니다. 프로파일러를 활성화하려면 런타임에 DD_PROFILING_ENABLED=true 환경 변수를 설정하세요.

통합 제거

orchestrion.tool.go 파일에서 가져오기를 수정하여 통합을 제거할 수 있습니다. orchestrion을 실행하기 전에 자체적으로 orchestrion.tool.go 파일을 생성할 수도 있습니다. 이 작업은 통합을 원하지 않는 경우, 또는 프로그램이 사용하지 않는 통합의 전이 종속성 수를 줄이고자 하는 경우에 할 수 있습니다. 기본적으로 Orchestrion은 github.com/DataDog/dd-trace-go/orchestrion/all/v2를 가져오며, 이것은 Orchestrion 통합이 있는 모든 라이브러리를 가져옵니다. 이 가져오기 대신 사용하려는 통합만 가져오기를 사용할 수 있습니다. 지원되는 통합 목록은 SDK 소스 코드를 참조하세요.

참고: 특정 통합을 가져오기로 하는 경우, 새 통합을 추가하고자 할 때마다 orchestrion.tool.go를 수동으로 업데이트해야 합니다.

Docker를 사용해 빌드하기

적합한 Docker 이미지를 생성하는 방법에 관한 자세한 내용은 Go의 APM을 위한 Dockerfile 생성을 참조하세요.

문제 해결

orchestrion이 관리하는 빌드 문제를 해결하려면 Go 컴파일 시간 계측 문제 해결을 참조하세요.

애플리케이션에 SDK 추가

먼저, 라이브러리 구성 설명서를 따라 코드에 SDK를 가져오고 시작합니다. 구성 지침 및 API 사용에 관한 상세한 정보는 API 설명서(또는 API 설명서 v1)를 참조하세요.

스팬을 생성하기 위해 Go 통합 활성화

스팬을 생성하려면 Go 통합을 활성화합니다. Datadog에는 일련의 플러그형 패키지가 있어서 일련의 라이브러리 및 프레임워크를 계측하기 위한 즉시 사용 가능한 지원을 제공합니다. 이러한 패키지 목록은 호환성 요구 사항 페이지에서 확인할 수 있습니다. 이러한 패키지를 애플리케이션에 가져온 다음 각 통합과 함께 목록으로 나열된 구성 지침을 따르세요.