기본 사용법

whatap-go-inst는 빌드 시 모니터링 코드를 자동으로 삽입하는 CLI 도구입니다. 소스코드를 직접 수정하지 않고 Go 애플리케이션에 와탭 모니터링을 추가할 수 있습니다.

이 문서에서는 whatap-go-inst의 설치와 기본 사용 방법을 안내합니다.

팁

API를 직접 사용하여 모니터링 코드를 추가하려면 수동 적용 가이드를 참고하세요.

지원 환경

whatap-go-inst를 사용하려면 다음 환경이 필요합니다.

항목	요구사항	비고
Go 버전	1.18 이상	계측된 코드 빌드 시 필요
OS	Linux	amd64, arm64

노트

whatap-go-inst 바이너리는 Go 설치 없이 실행할 수 있습니다. 단, 계측된 코드를 빌드하려면 Go 1.18 이상이 필요합니다.

빠른 시작

1단계: whatap-go-inst 설치

whatap-go-inst 설치 방법은 다음 3가지입니다. 환경에 맞는 방법을 선택하세요.

Go install 설치 (권장)

Go 1.21 이상에서 권장하는 설치 방법입니다.

go install github.com/whatap/go-api-inst/cmd/whatap-go-inst@latest

바이너리 직접 설치

Go 설치 없이 직접 설치하는 방법입니다. Go 1.18-1.20 사용자는 이 방법을 사용하세요.

# Linux (amd64)
curl -sSL https://github.com/whatap/go-api-inst/releases/latest/download/whatap-go-inst_linux_amd64.tar.gz | tar xz
sudo mv whatap-go-inst /usr/local/bin/

# Linux (arm64)
curl -sSL https://github.com/whatap/go-api-inst/releases/latest/download/whatap-go-inst_linux_arm64.tar.gz | tar xz
sudo mv whatap-go-inst /usr/local/bin/

소스에서 빌드

git clone https://github.com/whatap/go-api-inst.git
cd go-api-inst
go build -o whatap-go-inst .

2단계: 프로젝트 초기화

프로젝트 루트(go.mod가 있는 디렉토리)에서 실행하세요.

whatap-go-inst init

이 명령어는 다음 작업을 수행합니다:

프로젝트 분석 및 사용 중인 프레임워크 감지
whatap_inst.tool.go 파일 생성
go.mod에 whatap 의존성 추가

3단계: 빌드 및 실행

# 모니터링 코드가 자동으로 삽입되어 빌드됩니다
whatap-go-inst go build ./...

# 실행
./myapp

완료!

이제 WhaTap 모니터링 서비스에서 데이터를 확인할 수 있습니다.

💡 원본 코드를 전혀 변경하고 싶지 않다면?

wrap 모드를 사용하면 whatap_inst.tool.go 파일이나 go.mod 변경 없이 빌드할 수 있습니다.

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

wrap 모드 특징

원본 프로젝트 파일 변경 없음
첫 테스트나 임시 적용에 유용
매번 --wrap 옵션 필요

whatap-go-inst 상세 설명

작동 원리

whatap-go-inst는 빌드 시 소스코드를 분석하여 모니터링 코드를 자동으로 삽입합니다.

1. main() 함수 초기화

// 변경 전
func main() {
    // 애플리케이션 코드
}

// 변경 후
func main() {
    trace.Init(nil)         // 자동 추가
    defer trace.Shutdown()  // 자동 추가
    
    // 애플리케이션 코드
}

2. 웹 프레임워크 미들웨어

// 변경 전
r := gin.Default()
r.GET("/api", handler)

// 변경 후
r := gin.Default()
r.Use(whatapgin.Middleware())  // 자동 추가
r.GET("/api", handler)

3. 데이터베이스 호출

// 변경 전
db, _ := sql.Open("mysql", dsn)

// 변경 후
db, _ := whatapsql.Open("mysql", dsn)  // 자동 변경

지원하는 주요 라이브러리

웹 프레임워크: Gin, Echo, Fiber, Chi, Gorilla Mux, net/http, FastHTTP
데이터베이스: database/sql, sqlx, GORM v1/v2
캐시/NoSQL: Redis (go-redis, Redigo), MongoDB
외부 서비스: gRPC, Kafka (Sarama), Kubernetes client-go
로그: log, logrus, zap

전체 지원 라이브러리 목록 보기

분류	지원 라이브러리
웹 프레임워크	Gin, Echo v4, Fiber v2, Chi v5, Gorilla Mux, net/http, FastHTTP
데이터베이스	database/sql, sqlx, GORM v1/v2
Redis	go-redis v8/v9, Redigo
NoSQL	MongoDB
메시지큐	Kafka (Sarama - IBM/Shopify)
RPC	gRPC
Kubernetes	client-go
로그	log, logrus, zap

명령어

구분	명령어	설명	주요 사용
기본	`whatap-go-inst go build`	모니터링 코드를 삽입하여 빌드	일반 빌드
기본	`whatap-go-inst go run`	모니터링 코드를 삽입하여 실행	개발/테스트
기본	`whatap-go-inst go test`	모니터링 코드를 삽입하여 테스트	단위 테스트
고급	`whatap-go-inst inject`	계측 코드를 별도 디렉토리에 출력	코드 검토
고급	`whatap-go-inst remove`	삽입된 모니터링 코드 제거	계측 해제
유틸	`whatap-go-inst version`	버전 확인	버전 체크

팁

whatap-go-inst go 뒤에는 일반 go 명령어와 동일하게 사용할 수 있습니다.

# 예시: 일반 go 명령어처럼 사용
whatap-go-inst go build -o myapp -ldflags="-s -w" .

주요 옵션

whatap-go-inst go 옵션

옵션	설명
`--error-tracking`	에러 추적 코드 삽입 (`if err != nil` 패턴에 `trace.Error` 추가)

사용 예시:

# wrap 모드
whatap-go-inst go --wrap build ./...

# 에러 추적 포함
whatap-go-inst go --error-tracking build ./...

inject/remove 옵션

옵션	설명
`-s, --src`	소스코드 경로
`-o, --output`	출력 디렉토리
`--all`	(remove만) 수동 삽입 패턴도 제거 시도

사용 예시:

# 계측 코드 별도 저장
whatap-go-inst inject -s ./src -o ./instrumented

# 계측 코드 제거
whatap-go-inst remove -s ./instrumented -o ./clean

전역 옵션

모든 명령어에서 사용할 수 있는 공통 옵션입니다.

옵션	설명
`--verbose, -v`	상세 출력 (파일별 변환 내용 표시)
`--quiet, -q`	요약만 출력
`--config`	설정 파일 경로 (기본: `.whatap/config.yaml`)
`--report`	JSON 보고서 파일 경로

사용 예시:

# 상세 출력
whatap-go-inst -v go build ./...

# 설정 파일 지정
whatap-go-inst --config ./my-config.yaml go build ./...

자주 묻는 질문

원본 코드가 변경되나요?

원본 코드는 변경되지 않습니다. whatap-go-inst는 tmp 디렉토리에 소스코드를 복사한 후 의존성을 다운로드하고 빌드합니다.

빌드 결과물은 whatap-instrumented 디렉토리에 생성됩니다.

기존 go 명령어와 무엇이 다른가요?

whatap-go-inst go build는 일반 go build와 동일하게 작동하지만, 빌드 전에 모니터링 코드를 자동으로 삽입합니다. 모든 옵션과 플래그는 그대로 사용할 수 있습니다.

# 일반 빌드 명령어와 동일하게 사용
whatap-go-inst go build -o myapp -ldflags="-s -w" .

빌드 시간이 느려지나요?

tmp 디렉토리 복사, 의존성 다운로드, 코드 삽입 과정으로 인해 일반 빌드보다 시간이 더 소요됩니다.

계측이 적용되지 않는 것 같은데요?

다음을 확인해보세요:

# 빌드 캐시 삭제 후 재빌드
go clean -cache
whatap-go-inst go build ./...

# 디버그 모드로 상세 로그 확인
GO_API_AST_DEBUG=1 whatap-go-inst go build ./...

더 자세한 내용은 자동 적용 가이드를 참고하세요.

Docker 환경에서도 사용할 수 있나요?

네, Dockerfile에서 동일하게 사용할 수 있습니다:

FROM golang:1.21 AS builder

WORKDIR /app

# 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 .

FROM alpine:latest
COPY --from=builder /app/myapp /app/myapp
CMD ["/app/myapp"]

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

지원 환경​

빠른 시작​

1단계: whatap-go-inst 설치​

Go install 설치 (권장)​

바이너리 직접 설치​

소스에서 빌드​

2단계: 프로젝트 초기화​

3단계: 빌드 및 실행​

whatap-go-inst 상세 설명​

작동 원리​

1. main() 함수 초기화​

2. 웹 프레임워크 미들웨어​

3. 데이터베이스 호출​

지원하는 주요 라이브러리​

명령어​

주요 옵션​

whatap-go-inst go 옵션​

inject/remove 옵션​

전역 옵션​

자주 묻는 질문​

원본 코드가 변경되나요?​

기존 go 명령어와 무엇이 다른가요?​

빌드 시간이 느려지나요?​

계측이 적용되지 않는 것 같은데요?​

Docker 환경에서도 사용할 수 있나요?​

지원 환경

빠른 시작

1단계: whatap-go-inst 설치

Go install 설치 (권장)

바이너리 직접 설치

소스에서 빌드

2단계: 프로젝트 초기화

3단계: 빌드 및 실행

whatap-go-inst 상세 설명

작동 원리

1. main() 함수 초기화

2. 웹 프레임워크 미들웨어

3. 데이터베이스 호출

지원하는 주요 라이브러리

명령어

주요 옵션

whatap-go-inst go 옵션

inject/remove 옵션

전역 옵션

자주 묻는 질문

원본 코드가 변경되나요?

기존 go 명령어와 무엇이 다른가요?

빌드 시간이 느려지나요?

계측이 적용되지 않는 것 같은데요?

Docker 환경에서도 사용할 수 있나요?