Docker Go 설치

관리 > 에이전트 설치 > 하단의 애플리케이션 설치 클릭 > 설치 안내 중 Docker Go 탭 선택

Docker 컨테이너 기반의 Go 애플리케이션에 WhaTap 모니터링 에이전트를 설치하는 방법을 안내합니다. 다음 2가지 방법 중 선택하세요.

빠른 설치 방법: Dockerfile 작성부터 컨테이너 실행, 모니터링 데이터 확인까지 전체 설치 과정
배포 환경별 설정: 아키텍처(x64/ARM64), Kubernetes, Docker Compose 환경별 추가 설정 방법

노트

EKS Fargate는 지원 예정입니다.

팁

설치를 시작하기 전에 다음 정보를 준비하세요.

WhaTap 프로젝트 액세스 키 ([프로젝트 메뉴] > [관리] > [에이전트 설치]에서 확인)
WhaTap 수집 서버 IP 주소

빠른 설치 방법

3개 파일만으로 WhaTap 모니터링이 적용된 Docker 이미지를 빌드할 수 있습니다.

1단계. 필수 파일 준비

프로젝트 루트에 다음 3개 파일을 생성하세요.

1. Dockerfile
2. entrypoint.sh
3. main.go (예제)

# ============================================
# Build stage - whatap-go-inst 빌드
# ============================================
FROM golang:1.21-alpine AS builder

WORKDIR /app

# whatap-go-inst 설치
#RUN go install github.com/whatap/go-api-inst/cmd/whatap-go-inst@latest
RUN wget -qO- https://github.com/whatap/go-api-inst/releases/latest/download/whatap-go-inst_linux_amd64.tar.gz | tar xz -C /usr/local/bin/

# 소스 복사
COPY go.mod go.sum ./
RUN go mod download
COPY . .

# whatap-go-inst 빌드
RUN whatap-go-inst go build -o /app/main .

# ============================================
# Runtime stage
# ============================================
FROM alpine:latest

WORKDIR /app

# WhaTap 데이터 중계 에이전트 설치
RUN apk add --no-cache wget
RUN wget https://s3.ap-northeast-2.amazonaws.com/repo.whatap.io/alpine/x86_64/whatap-agent.tar.gz
RUN tar -xvzf whatap-agent.tar.gz -C /
RUN rm whatap-agent.tar.gz

# 애플리케이션 복사
COPY --from=builder /app/main .

# 시작 스크립트
COPY entrypoint.sh /app/
RUN chmod +x /app/entrypoint.sh

ENTRYPOINT ["/app/entrypoint.sh"]

#!/bin/sh

# whatap.conf 생성 (환경변수에서)
mkdir -p /app/whatap_home
cat > /app/whatap_home/whatap.conf << EOF
license=${WHATAP_LICENSE}
whatap.server.host=${WHATAP_SERVER_HOST}
app_name=${WHATAP_APP_NAME:-myapp}
EOF

export WHATAP_HOME=/app/whatap_home

# 데이터 중계 에이전트 시작 후 애플리케이션 실행
/usr/whatap/agent/whatap-agent start
exec ./main

package main

import "github.com/gin-gonic/gin"

func main() {
    r := gin.Default()
    r.GET("/", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "Hello WhaTap"})
    })
    r.Run(":8080")
}

2단계. 이미지 빌드

docker build -t my-go-app .

3단계. 컨테이너 실행

환경변수로 WhaTap 설정을 전달합니다.

docker run -d \
  -e WHATAP_LICENSE={액세스 키} \
  -e WHATAP_SERVER_HOST={수집 서버 IP} \
  -e WHATAP_APP_NAME=myapp \
  -p 8080:8080 \
  my-go-app

4단계. 모니터링 확인

애플리케이션에 트래픽 발생: curl http://localhost:8080
WhaTap 모니터링 서비스에서 데이터 확인

데이터가 보이지 않나요?

문제 해결 섹션을 참고하세요.

배포 환경별 설정

아키텍처별 Dockerfile 설정

앞의 빠른 시작 예제는 x64 (AMD64) 기준입니다. ARM64 환경에서는 에이전트 다운로드 URL만 변경하세요.

WhaTap 에이전트 아키텍처별 URL

아키텍처	에이전트 다운로드 URL
x64 (AMD64)	`https://s3.ap-northeast-2.amazonaws.com/repo.whatap.io/alpine/x86_64/whatap-agent.tar.gz`
ARM64 (AArch64)	`https://s3.ap-northeast-2.amazonaws.com/repo.whatap.io/alpine/aarch64/whatap-agent.tar.gz`

ARM64 Dockerfile 수정 예제

Dockerfile의 에이전트 설치 부분만 변경:

# Runtime stage에서 변경
RUN apk add --no-cache wget && \
    wget https://s3.ap-northeast-2.amazonaws.com/repo.whatap.io/alpine/aarch64/whatap-agent.tar.gz && \
    tar -xvzf whatap-agent.tar.gz -C / && rm whatap-agent.tar.gz

ARM64 전체 Dockerfile 보기

FROM golang:1.21-alpine AS builder

WORKDIR /app

# whatap-go-inst 설치
#RUN go install github.com/whatap/go-api-inst/cmd/whatap-go-inst@latest
RUN wget -qO- https://github.com/whatap/go-api-inst/releases/latest/download/whatap-go-inst_linux_amd64.tar.gz | tar xz -C /usr/local/bin/

COPY go.mod go.sum ./
RUN go mod download
COPY . .

RUN whatap-go-inst go build -o /app/main .

FROM alpine:latest

WORKDIR /app

RUN apk add --no-cache wget && \
    wget https://s3.ap-northeast-2.amazonaws.com/repo.whatap.io/alpine/aarch64/whatap-agent.tar.gz && \
    tar -xvzf whatap-agent.tar.gz -C / && rm whatap-agent.tar.gz

COPY --from=builder /app/main .
COPY entrypoint.sh /app/
RUN chmod +x /app/entrypoint.sh

ENTRYPOINT ["/app/entrypoint.sh"]

Kubernetes 배포

Docker 이미지를 빌드한 후 Kubernetes 클러스터에 배포할 수 있습니다.

1단계: Docker 이미지 레지스트리 푸시

# 이미지 태그 지정
docker tag my-go-app:latest your-registry/my-go-app:v1.0

# 레지스트리 푸시
docker push your-registry/my-go-app:v1.0

2단계: WhaTap 설정 Secret 생성

kubectl create secret generic whatap-secret \
  --from-literal=license={액세스 키}

3단계: Deployment 배포

deployment.yaml
service.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-go-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-go-app
  template:
    metadata:
      labels:
        app: my-go-app
    spec:
      containers:
      - name: my-go-app
        image: your-registry/my-go-app:v1.0
        ports:
        - containerPort: 8080
        env:
        - name: WHATAP_LICENSE
          valueFrom:
            secretKeyRef:
              name: whatap-secret
              key: license
        - name: WHATAP_SERVER_HOST
          value: "{수집 서버 IP}"
        - name: WHATAP_APP_NAME
          value: "my-go-app"
        # Kubernetes 메타데이터 (선택사항)
        - name: NODE_IP
          valueFrom:
            fieldRef:
              fieldPath: status.hostIP
        - name: NODE_NAME
          valueFrom:
            fieldRef:
              fieldPath: spec.nodeName
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name

apiVersion: v1
kind: Service
metadata:
  name: my-go-app
spec:
  selector:
    app: my-go-app
  ports:
  - port: 80
    targetPort: 8080
  type: LoadBalancer

kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

환경변수 설명

필수 환경변수

환경변수	설명	예시
`WHATAP_LICENSE`	WhaTap 프로젝트 액세스 키	`x4t2r...`
`WHATAP_SERVER_HOST`	WhaTap 수집 서버 IP	`13.124.11.223`
`WHATAP_APP_NAME`	애플리케이션 이름 (선택)	`my-go-app`

Kubernetes 메타데이터 (선택사항)

파드의 실행 위치 정보를 WhaTap에 전달하려면 추가하세요:

환경변수	설명
`NODE_IP`	파드가 실행 중인 노드의 IP
`NODE_NAME`	파드가 실행 중인 노드의 이름
`POD_NAME`	파드의 이름

Docker Compose

docker-compose.yml
version: '3.8'

services:
  my-go-app:
    build: .
    ports:
      - "8080:8080"
    environment:
      - WHATAP_LICENSE={액세스 키}
      - WHATAP_SERVER_HOST={수집 서버 IP}
      - WHATAP_APP_NAME=my-go-app
    restart: unless-stopped

docker-compose up -d

문제 해결

모니터링 데이터가 보이지 않는 경우

1단계: 환경변수 확인

컨테이너 내부에서 환경변수가 올바르게 설정되었는지 확인:

docker exec -it <container_id> sh
echo $WHATAP_LICENSE
echo $WHATAP_SERVER_HOST
cat /app/whatap_home/whatap.conf

2단계: 에이전트 실행 확인

# 에이전트 프로세스 확인
docker exec -it <container_id> ps -ef | grep whatap

# 에이전트 로그 확인
docker exec -it <container_id> cat /app/whatap_home/logs/whatap-*.log

정상 출력 예시:

root  12  1  0 Jan21 ?  00:00:03 /usr/whatap/agent/whatap-agent

3단계: 네트워크 확인

WhaTap 수집 서버(6600 포트)로 아웃바운드 연결이 가능한지 확인:

docker exec -it <container_id> nc -zv {수집 서버 IP} 6600

계측이 적용되지 않는 경우

whatap-go-inst 초기화 확인

빌드 로그에서 whatap-go-inst init 실행 여부 확인:

# 디버그 모드로 재빌드
docker build --progress=plain -t my-go-app .

계측 상세 로그 확인

# 빌드 시 디버그 출력
GO_API_AST_DEBUG=1 whatap-go-inst go build ./...

일반적인 문제와 해결 방법

증상	원인	해결 방법
데이터 미수신	환경변수 미설정	`WHATAP_LICENSE`, `WHATAP_SERVER_HOST` 확인
에이전트 시작 실패	네트워크 차단	6600 포트 아웃바운드 허용
계측 미적용	초기화 누락	Dockerfile에 `whatap-go-inst init` 추가 확인
ARM64 에러	잘못된 바이너리	아키텍처별 에이전트 URL 확인

추가 지원

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

WhaTap 지원 센터 문의
다음 정보 제공:
- Dockerfile 전체 내용
- 에이전트 로그 (/app/whatap_home/logs/)
- docker logs <container_id> 출력

빠른 설치 방법​

1단계. 필수 파일 준비​

2단계. 이미지 빌드​

3단계. 컨테이너 실행​

4단계. 모니터링 확인​

배포 환경별 설정​

아키텍처별 Dockerfile 설정​

WhaTap 에이전트 아키텍처별 URL​

ARM64 Dockerfile 수정 예제​

Kubernetes 배포​

1단계: Docker 이미지 레지스트리 푸시​

2단계: WhaTap 설정 Secret 생성​

3단계: Deployment 배포​

환경변수 설명​

Docker Compose​

문제 해결​

모니터링 데이터가 보이지 않는 경우​

1단계: 환경변수 확인​

2단계: 에이전트 실행 확인​

3단계: 네트워크 확인​

계측이 적용되지 않는 경우​

whatap-go-inst 초기화 확인​

계측 상세 로그 확인​

일반적인 문제와 해결 방법​

추가 지원​