본문으로 건너뛰기

기본 사용법

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

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

팁

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

지원 환경​

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

항목요구사항비고
Go 버전1.18 이상계측된 코드 빌드 시 필요
OSLinuxamd64, 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단계 빌드 및 실행​

# 모니터링 코드가 자동으로 삽입되어 빌드됩니다
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
Redisgo-redis v8/v9, Redigo
NoSQLMongoDB
메시지큐Kafka (Sarama - IBM/Shopify)
RPCgRPC
Kubernetesclient-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)
--reportJSON 보고서 파일 경로

사용 예시:

# 상세 출력
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 설치 가이드를 참고하세요.

최종 수정: