OpenTelemetry Go（LoongSuite）¶

LoongSuite Go는 OpenTelemetry를 기반으로 한 Go 컴파일 타임 자동 인스트루먼테이션 도구입니다. 비즈니스 코드를 수정할 필요 없이 기존 go build를 otel go build로 대체하기만 하면 컴파일 중에 지원되는 프레임워크 및 컴포넌트에 OpenTelemetry SDK 및 인스트루먼테이션 로직을 주입할 수 있습니다.

이 문서에서는 DataKit의 OpenTelemetry 수집기를 사용하여 LoongSuite가 OTLP를 통해 전송하는 Trace 및 Metric을 수신하고 Guance로 전달합니다:

Go 소스 코드 -- otel go build --> 인스트루먼테이션된 Go 바이너리 -- OTLP --> DataKit --> Guance

!!! note

LoongSuite의 "제로 코드"는 비즈니스 코드를 수정할 필요가 없음을 의미하며, 재빌드가 필요 없음을 의미하지는 않습니다. 인스트루먼테이션은 컴파일 단계에서 발생하므로 이미 생성된 Go 바이너리에 LoongSuite를 직접 추가할 수 없습니다. `otel go build`를 사용하여 다시 컴파일하고 새로운 바이너리를 배포해야 합니다.

전제 조건¶

• DataKit이 설치되어 있고, DataKit이 대상 Guance 워크스페이스에 연결되어 있어야 합니다.
• Go 애플리케이션에서 DataKit으로 네트워크 접근이 가능해야 합니다. OTLP/HTTP는 DataKit HTTP 포트 9529를 사용하고, OTLP/gRPC는 기본적으로 4317을 사용합니다.
• 애플리케이션이 표준 go build로 정상적으로 컴파일되어야 합니다.
• Go 버전, 운영 체제 및 아키텍처가 LoongSuite의 호환성 요구 사항을 충족해야 합니다.
• 애플리케이션이 사용하는 프레임워크 또는 컴포넌트가 LoongSuite의 지원 목록에 포함되어 있어야 합니다.

이 문서는 Linux AMD64 호스트를 예시로 하며, Kubernetes 배포는 포함하지 않습니다.

1. OpenTelemetry 수집기 활성화¶

DataKit 설치 디렉터리 아래 conf.d/opentelemetry로 이동합니다. 수집기 구성 파일이 아직 생성되지 않은 경우 샘플 파일을 복사합니다:

cd /usr/local/datakit/conf.d/opentelemetry
sudo cp opentelemetry.conf.sample opentelemetry.conf

opentelemetry.conf에 최소한 다음 수신 구성이 포함되어 있는지 확인합니다:

[[inputs.opentelemetry]]
  # 사용자 정의 속성을 태그로 유지하려면 여기에 화이트리스트를 추가하십시오.
  # 속성 이름의 점은 밑줄로 변환됩니다(예: team.name -> team_name).
  customer_tags = ["team", "project"]

  [inputs.opentelemetry.http]
    http_status_ok = 200
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"

  [inputs.opentelemetry.grpc]
    addr = "127.0.0.1:4317"
    max_payload = 16777216

위 구성은 다음 수신 주소를 활성화합니다:

애플리케이션이 DataKit과 동일한 호스트에 있지 않은 경우 실제 배포에 따라 DataKit HTTP 수신 주소, 방화벽 또는 기타 네트워크 액세스 제어를 조정해야 합니다. OTLP/gRPC를 사용하는 경우 addr을 애플리케이션이 접근 가능한 수신 주소(예: 0.0.0.0:4317)로 변경해야 합니다. OTLP 수신 포트를 공용 네트워크에 직접 노출하지 마십시오.

DataKit을 다시 시작하여 구성을 적용합니다:

sudo datakit service restart

DataKit HTTP 서비스에 접근 가능한지 확인합니다:

curl http://127.0.0.1:9529/v1/ping

2. 애플리케이션 OpenTelemetry 연동¶

LoongSuite 설치¶

LoongSuite 공식 GitHub Release에서 Linux AMD64 실행 파일을 다운로드합니다:

sudo curl -fL \
  https://github.com/alibaba/loongsuite-go/releases/latest/download/otel-linux-amd64 \
  -o /usr/local/bin/otel
sudo chmod +x /usr/local/bin/otel

ARM64 호스트의 경우 파일 이름을 otel-linux-arm64로 바꿉니다. 다른 운영 체제 및 아키텍처는 LoongSuite Releases에서 해당 파일을 선택하십시오.

도구가 실행 가능한지 확인합니다:

otel version
go version

프로덕션 환경에서는 명시적인 버전 번호가 포함된 Release 다운로드 주소를 사용하여 LoongSuite 버전을 고정하고, 업그레이드 전에 호환성, 릴리스 노트를 확인하고 컴파일 및 분산 추적 회귀 테스트를 수행하는 것이 좋습니다.

인스트루먼테이션 전 확인¶

원래 명령으로 프로젝트가 정상적으로 컴파일되는지 확인합니다:

go build ./...

프로젝트가 이미 OpenTelemetry Go API, SDK 또는 Contrib 인스트루먼테이션 라이브러리에 직접 의존하는 경우, 이러한 의존성이 현재 LoongSuite 버전의 요구 사항과 일치하는지 확인해야 합니다:

go list -m all | grep 'go.opentelemetry.io'

LoongSuite는 애플리케이션에 SDK 초기화 로직을 주입하고 OpenTelemetry 자체를 인스트루먼테이션합니다. 프로젝트에 이미 호환되지 않는 OpenTelemetry 의존성 또는 중복된 SDK 초기화 로직이 있는 경우 컴파일 실패, 중복 Span 또는 컨텍스트 중단이 발생할 수 있습니다. 이러한 프로젝트는 먼저 공식 호환성 표에 따라 의존성 버전을 통일해야 합니다. 애플리케이션이 SDK를 직접 제어해야 하는 경우 OpenTelemetry Go SDK를 사용하는 것이 좋습니다.

LoongSuite를 사용한 컴파일¶

Go 프로젝트 디렉터리로 이동하여 원래 빌드 명령 앞에 otel을 추가합니다:

otel go build -o ./bin/order-service ./cmd/order-service

다른 일반적인 빌드 방식도 동일하게 기존 go build 인수를 유지합니다. 예:

otel go build
otel go build -trimpath -ldflags="-s -w" -o ./bin/order-service ./cmd/order-service

LoongSuite 컴파일은 전처리, 인스트루먼테이션 및 의존성 처리 단계를 추가하므로 첫 번째 빌드는 일반적으로 기본 go build보다 현저히 느립니다. 재사용 가능한 Go 빌드 캐시를 구성하여 후속 빌드 시간을 단축할 수 있습니다:

otel set -gocache=/var/tmp/loongsuite-go-cache

환경 변수를 통해 CI 또는 단일 빌드에 대한 캐시를 지정할 수도 있습니다:

export OTELTOOL_GO_CACHE="/var/tmp/loongsuite-go-cache"
otel go build -o ./bin/order-service ./cmd/order-service

!!! warning

이후 릴리스 프로세스에서는 `otel go build`로 생성된 바이너리를 배포해야 합니다. 일반 `go build`로 아티팩트를 덮어쓰면 런타임에 LoongSuite 자동 인스트루먼테이션이 포함되지 않습니다.

OTLP/HTTP 구성 및 시작¶

다음 예제는 OTLP/HTTP + Protobuf를 통해 Trace 및 Metric을 로컬 DataKit으로 전송합니다. 일반 endpoint를 http://127.0.0.1:9529/otel로 설정하면 Exporter가 각각 /v1/traces 및 /v1/metrics를 추가하여 최종적으로 DataKit의 /otel/v1/* 수신 경로에 매핑됩니다.

export OTEL_SERVICE_NAME="order-service"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=prod,service.version=1.0.0,team=backend"

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:9529/otel"
export OTEL_EXPORTER_OTLP_INSECURE="true"

# 1.0은 전체 샘플링을 의미하며, 연동 검증 단계에서만 사용하는 것이 좋습니다.
export OTEL_TRACE_SAMPLER="1.0"

./bin/order-service

실행 매개변수는 컴파일 호스트가 아닌 인스트루먼테이션된 바이너리의 실제 실행 환경에 구성되어야 합니다. 시작 후 지원되는 프레임워크가 제공하는 엔드포인트를 요청하고 데이터베이스, HTTP 클라이언트 또는 메시지 큐 호출을 트리거하여 검증 가능한 Span 및 Metric을 생성합니다.

OTLP/gRPC 사용¶

OTLP/gRPC로 변경하려면 프로토콜과 endpoint를 바꿉니다. gRPC 주소에는 /v1/traces와 같은 HTTP 경로를 추가할 수 없습니다:

export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4317"
export OTEL_EXPORTER_OTLP_INSECURE="true"

3. 데이터 전송 매개변수¶

LoongSuite는 컴파일 중에 OpenTelemetry SDK 초기화 로직을 주입합니다. 인스트루먼테이션된 애플리케이션은 런타임에 환경 변수를 통해 Exporter, endpoint, 샘플링 및 리소스 속성을 조정할 수 있습니다.

리소스 및 Exporter 매개변수¶

일반 HTTP endpoint를 사용할 때는 http://<DataKit-IP>:9529/otel을 입력합니다. 신호 전용 endpoint를 사용하는 경우 /otel/v1/traces 또는 /otel/v1/metrics를 포함한 전체 경로를 입력해야 합니다. DataKit의 OTLP/HTTP 수집은 Protobuf만 지원하므로 http/json을 구성하지 마십시오.

샘플링 및 Metric 매개변수¶

!!! warning

LoongSuite가 현재 사용하는 샘플링 변수는 `OTEL_TRACE_SAMPLER`이며, OpenTelemetry SDK에서 일반적으로 사용하는 `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG`와 이름이 다릅니다. 설치된 LoongSuite 버전의 [SDK 구성 설명](https://github.com/alibaba/loongsuite-go/blob/main/docs/user/sdk-config.md){:target="_blank"}을 기준으로 하십시오.

프로덕션 환경에서는 트래픽, 데이터 예산 및 문제 해결 요구 사항에 따라 샘플링 비율을 조정해야 합니다. 업스트림 및 다운스트림 서비스는 호환되는 W3C Trace Context 전파를 유지하여 교차 서비스 호출 시 연결이 끊어지지 않도록 해야 합니다.

LoongSuite 빌드 매개변수¶

다음 변수는 LoongSuite 컴파일 도구만 제어하며, 인스트루먼테이션된 바이너리의 데이터 전송은 제어하지 않습니다:

예를 들어, 임시로 상세 컴파일 로그를 출력합니다:

export OTELTOOL_DEBUG="true"
export OTELTOOL_VERBOSE="true"
otel go build -o ./bin/order-service ./cmd/order-service

문제 해결이 완료되면 Debug 및 Verbose를 비활성화하여 로그 양을 줄입니다.

필드 매핑¶

LoongSuite가 전송하는 OTLP Span Attributes는 DataKit OpenTelemetry 수집기에 의해 분산 추적 필드로 변환됩니다. 일반적인 매핑은 다음과 같습니다:

LoongSuite가 전송하는 다른 Attributes를 태그로 승격시키려면 DataKit opentelemetry.conf에서 customer_tags를 구성할 수 있습니다. customer_tags는 정규식을 지원하며, 일치하는 속성 이름의 .는 _로 변환됩니다:

[[inputs.opentelemetry]]
  customer_tags = [
    "reg:^db\\.query\\.parameter\\.",
    "reg:^kratos\\.service\\.meta\\.",
    "reg:^gen_ai\\.other_input\\.",
    "reg:^gen_ai\\.other_output\\.",
  ]

사용자 ID, 주문 번호 등 높은 카디널리티 값을 태그로 일괄 승격시키지 말고, 비밀번호, 토큰, 데이터베이스 전체 연결 문자열 등 민감한 정보를 전송하지 마십시오.

연동 확인¶

1. otel go build를 사용하여 컴파일하고 새 바이너리를 시작합니다.
2. 지원되는 웹 프레임워크에서 처리하는 엔드포인트를 요청하고 데이터베이스, HTTP 클라이언트 또는 메시지 큐 호출을 트리거합니다.
3. OTLP/HTTP를 사용하여 전송하는 경우 DataKit 호스트에서 수신 로그를 확인합니다:

sudo tail -f /usr/local/datakit/log/gin.log | grep '/otel/v1/'

/otel/v1/traces 또는 /otel/v1/metrics에 대한 POST 요청이 나타나고 응답 코드가 200이면 DataKit이 데이터를 수신한 것입니다. 그런 다음 Guance의 '애플리케이션 성능 모니터링(APM) > 분산 추적'으로 이동하여 service:order-service로 조회합니다. Metric은 최소 하나의 내보내기 주기가 지난 후에 조회합니다.

데이터가 없는 경우 다음을 순서대로 확인하십시오:

• 배포된 것이 otel go build로 생성된 새 바이너리인지 확인합니다.
• OTEL_SERVICE_NAME, Exporter, 프로토콜 및 endpoint가 실제 실행 중인 프로세스에 구성되어 있는지 확인합니다.
• 애플리케이션이 사용하는 프레임워크 및 버전이 LoongSuite 지원 목록에 있는지 확인합니다.
• LoongSuite와 프로젝트의 기존 OpenTelemetry 의존성이 호환되는지 확인합니다.
• DataKit OpenTelemetry 수집기가 활성화되어 있고 재시작되어 적용되었는지 확인합니다.
• 애플리케이션에서 DataKit으로의 네트워크 및 포트 접근이 가능한지 확인합니다.

일반 go build는 성공하지만 otel go build가 실패하는 경우 임시로 OTELTOOL_DEBUG=true 및 OTELTOOL_VERBOSE=true를 활성화하여 실패하는 특정 인스트루먼테이션 규칙을 찾습니다. 필요한 경우 otel set -disable=<rule-name>을 사용하여 문제가 되는 규칙을 일시적으로 비활성화하고 LoongSuite Issues에 피드백을 보냅니다.

참고¶

• LoongSuite Go
• LoongSuite 지원 프레임워크 및 컴포넌트
• LoongSuite SDK 구성
• LoongSuite 빌드 도구 구성
• OpenTelemetry Go 제로 코드 인스트루먼테이션
• DataKit OpenTelemetry 수집기