본문으로 건너뛰기

트러블슈팅

whatap-go-inst 사용 시 발생할 수 있는 문제와 해결 방법을 안내합니다.

계측이 적용되지 않을 때​

1단계: 빌드 캐시 삭제​

# 빌드 캐시 삭제
go clean -cache

# 재빌드
whatap-go-inst go build ./...

2단계: 디버그 모드 확인​

# 디버그 출력으로 계측 과정 확인
GO_API_AST_DEBUG=1 whatap-go-inst go build ./...

일반적인 문제 해결​

특정 파일만 계측되지 않음​

원인:

  • 파일이 제외 패턴에 포함됨
  • 생성된 코드 파일 (*.pb.go, *_generated.go 등)

확인 방법:

# 스킵된 파일 확인
GO_API_AST_DEBUG=1 whatap-go-inst go build ./... 2>&1 | grep "SKIP"

해결 방법:

제외 패턴을 조정하거나 특정 파일 제외를 해제합니다. 자세한 내용은 설정 가이드 - 제외 패턴을 참고하세요.

빌드는 성공하지만 데이터가 보이지 않음​

1. 에이전트 실행 확인​

ps -ef | grep whatap_agent

없는 경우:

# 에이전트 시작
/usr/whatap/agent/whatap_agent -d

2. main() 초기화 확인​

# main() 함수에 trace.Init이 있는지 확인
GO_API_AST_DEBUG=1 whatap-go-inst go build ./... 2>&1 | grep "trace.Init"

3. whatap.conf 설정 확인​

cat /usr/whatap/agent/whatap.conf

필수 설정:

license={액세스 키}
whatap.server.host={수집 서버 IP}

Docker 환경에서 계측 안 됨​

문제: 멀티스테이지 빌드에서 whatap-go-inst가 설치되지 않음

해결 방법:

FROM golang:1.21 AS builder

# whatap-go-inst 설치
RUN go install github.com/whatap/go-api-inst/cmd/whatap-go-inst@latest

# 초기화 및 빌드
COPY . .
RUN whatap-go-inst go build -o /app/myapp .

자세한 내용은 Docker 설치 가이드를 참고하세요.

실행 모드 비교​

whatap-go-inst는 여러 실행 모드를 제공합니다. 상황에 맞는 모드를 선택하세요.

모드 비교표​

모드명령어원본 변경의존성 자동권장 용도
기본 wrap 모드whatap-go-inst go build❌✅권장
inject 모드whatap-go-inst inject별도 출력❌코드 검토/CI

기본 wrap 모드 (권장)​

# init 없이 바로 빌드
whatap-go-inst go --wrap build ./...

특징:

  • ✅ 원본 파일 전혀 변경 안 됨
  • ✅ 변경된 파일을 ./whatap-intrumented 에 저장. 오류 분석 용이.

사용 사례:

  • CI/CD에서 선택적 계측

inject 모드​

# 계측된 코드를 별도 디렉토리에 출력
whatap-go-inst inject -s ./src -o ./instrumented

# 출력된 코드로 빌드
cd instrumented
go build ./...

특징:

  • ✅ 계측된 코드를 별도로 저장
  • ✅ 원본과 계측 코드 비교 가능
  • ⚠️ 의존성 수동 설치 필요
  • ⚠️ 빌드 전 inject 실행 필요

사용 사례:

  • 계측 결과 검토
  • CI/CD 파이프라인에서 사전 계측
  • 원본과 변환 코드 diff 확인

go-api에서 전환하기​

기존에 go-api를 직접 사용한 프로젝트를 whatap-go-inst로 전환하는 방법입니다.

1단계: 기존 whatap 코드 제거​

# 자동 삽입 패턴만 제거
whatap-go-inst remove -s . -o ./cleaned

# 수동 삽입 패턴도 제거 시도
whatap-go-inst remove --all -s . -o ./cleaned

2단계: 변경 사항 확인​

# diff로 차이 확인
diff -r . ./cleaned

# 또는 git diff
cp -r ./cleaned/* .
git diff

3단계: 커스텀 코드 복원​

remove --all로 제거되지 않은 패턴이나 필요한 커스텀 코드를 수동으로 복원합니다.

// 예: 커스텀 트랜잭션 코드는 유지
ctx, _ := trace.Start(context.Background(), "CustomTx")
defer trace.End(ctx, nil)

4단계: whatap-go-inst로 빌드​

whatap-go-inst go build ./...
주의

자동 제거되지 않는 패턴:

  • 변수 할당: ctx := trace.Start(...)
  • 클로저 패턴: whatapsql.Wrap(...)
  • 복잡한 커스텀 계측

이런 패턴은 경고 메시지가 출력되며 수동으로 제거해야 합니다.

추가 지원​

위 방법으로 해결되지 않는 경우:

  1. 디버그 로그 수집
   GO_API_AST_DEBUG=1 whatap-go-inst go build ./... > debug.log 2>&1
  1. 환경 정보 수집
   go version
   whatap-go-inst version
   cat .whatap/config.yaml
  1. WhaTap 지원 센터 문의
    • 디버그 로그
    • 환경 정보
    • 재현 가능한 최소 예제
여전히 해결되지 않나요?

기본 계측으로 처리할 수 없는 경우 사용자 정의 계측을 참고하세요.

최종 수정: