본문으로 건너뛰기

Docker 환경 설치

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

  • 빠른 설치 방법: Dockerfile 작성부터 컨테이너 실행, 모니터링 데이터 확인까지 전체 설치 과정

  • 배포 환경별 설정: 아키텍처(x64/ARM64), Kubernetes, Docker Compose 환경별 추가 설정 방법

팁

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

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

빠른 설치 방법​

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

1단계. 필수 파일 준비​

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

# ============================================
# 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"]

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단계. 모니터링 확인​

  1. 애플리케이션에 트래픽 발생: curl http://localhost:8080
  2. 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 배포​

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
kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

환경변수 설명​

필수 환경변수

환경변수설명예시
WHATAP_LICENSEWhaTap 프로젝트 액세스 키x4t2r...
WHATAP_SERVER_HOSTWhaTap 수집 서버 IP13.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

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

계측 상세 로그 확인​

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

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

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

추가 지원​

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

  1. WhaTap 지원 센터 문의

  2. 다음 정보 제공:

    • Dockerfile 전체 내용
    • 에이전트 로그 (/app/whatap_home/logs/)
    • docker logs <container_id> 출력
최종 수정: