Docker environment installation

This guide provides instructions on how to install the WhaTap monitoring agent in Docker container-based Go applications. Choose one of the following two methods:

Quick installation method: Complete installation process from writing Dockerfile to running containers and checking monitoring data
Configuration by deployment environment: Additional configuration methods for each architecture (x64/ARM64), Kubernetes, and Docker Compose environment

Tip

Before starting the installation, prepare the following information:

WhaTap project access key (check from [Project menu] > [Management] > [Agent installation])
WhaTap collection server IP address

Quick installation method

You can build a Docker image with WhaTap monitoring applied using only 3 files.

Step 1. Prepare required files

Create the following 3 files in the project root.

1. Dockerfile
2. entrypoint.sh
3. main.go (example)

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

WORKDIR /app

# Install 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 source
COPY go.mod go.sum ./
RUN go mod download
COPY . .

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

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

WORKDIR /app

# Install WhaTap data relay agent
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 application
COPY --from=builder /app/main .

# Startup script
COPY entrypoint.sh /app/
RUN chmod +x /app/entrypoint.sh

ENTRYPOINT ["/app/entrypoint.sh"]

#!/bin/sh

# Generate whatap.conf (from environment variables)
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

# Start data relay agent and run application
/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")
}

Step 2. Build image

docker build -t my-go-app .

Step 3. Run container

Pass WhaTap configuration through environment variables.

docker run -d \
  -e WHATAP_LICENSE={access key} \
  -e WHATAP_SERVER_HOST={collection server IP} \
  -e WHATAP_APP_NAME=myapp \
  -p 8080:8080 \
  my-go-app

Step 4. Check monitoring

Generate traffic to the application: curl http://localhost:8080
Check data in WhaTap Monitoring Service

Don't see any data?

Refer to the Troubleshooting section.

Configuration by deployment environment

Dockerfile configuration by architecture

The quick start example above is based on x64 (AMD64). For ARM64 environments, only change the agent download URL.

WhaTap agent URLs by architecture

Architecture	Agent download 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 modification example

Only change the agent installation part in the Dockerfile:

# Change in 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

View complete ARM64 Dockerfile

FROM golang:1.21-alpine AS builder

WORKDIR /app

# Install 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 deployment

After building the Docker image, you can deploy it to a Kubernetes cluster.

Step 1: Push Docker image to registry

# Tag image
docker tag my-go-app:latest your-registry/my-go-app:v1.0

# Push to registry
docker push your-registry/my-go-app:v1.0

Step 2: Create WhaTap configuration Secret

kubectl create secret generic whatap-secret \
  --from-literal=license={access key}

Step 3: Deploy 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: "{collection server IP}"
        - name: WHATAP_APP_NAME
          value: "my-go-app"
        # Kubernetes metadata (optional)
        - 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

Environment variable description

Required environment variables

Environment variable	Description	Example
`WHATAP_LICENSE`	WhaTap project access key	`x4t2r...`
`WHATAP_SERVER_HOST`	WhaTap collection server IP	`13.124.11.223`
`WHATAP_APP_NAME`	Application name (optional)	`my-go-app`

Kubernetes metadata (optional)

Add these to pass pod execution location information to WhaTap:

Environment variable	Description
`NODE_IP`	IP of the node where the pod is running
`NODE_NAME`	Name of the node where the pod is running
`POD_NAME`	Name of the pod

Docker Compose

docker-compose.yml
version: '3.8'

services:
  my-go-app:
    build: .
    ports:
      - "8080:8080"
    environment:
      - WHATAP_LICENSE={access key}
      - WHATAP_SERVER_HOST={collection server IP}
      - WHATAP_APP_NAME=my-go-app
    restart: unless-stopped

docker-compose up -d

Troubleshooting

When monitoring data is not visible

Step 1: Check environment variables

Check if environment variables are correctly set inside the container:

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

Step 2: Check agent execution

# Check agent process
docker exec -it <container_id> ps -ef | grep whatap

# Check agent logs
docker exec -it <container_id> cat /app/whatap_home/logs/whatap-*.log

Normal output example:

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

Step 3: Check network

Check if outbound connection to WhaTap collection server (port 6600) is possible:

docker exec -it <container_id> nc -zv {collection server IP} 6600

When instrumentation is not applied

Check detailed instrumentation logs

# Debug output during build
GO_API_AST_DEBUG=1 whatap-go-inst go build ./...

Common issues and solutions

Symptom	Cause	Solution
Data not received	Environment variables not set	Check `WHATAP_LICENSE`, `WHATAP_SERVER_HOST`
Agent fails to start	Network blocked	Allow port 6600 outbound
Instrumentation not applied	Initialization missing	Check that `whatap-go-inst init` is added to Dockerfile
ARM64 error	Incorrect binary	Check agent URL for architecture

Additional support

If the above methods do not resolve the issue:

Contact WhaTap Support Center
Provide the following information:
- Complete Dockerfile content
- Agent logs (/app/whatap_home/logs/)
- docker logs <container_id> output

Quick installation method​

Step 1. Prepare required files​

Step 2. Build image​

Step 3. Run container​

Step 4. Check monitoring​

Configuration by deployment environment​

Dockerfile configuration by architecture​

WhaTap agent URLs by architecture​

ARM64 Dockerfile modification example​

Kubernetes deployment​

Step 1: Push Docker image to registry​

Step 2: Create WhaTap configuration Secret​

Step 3: Deploy Deployment​

Environment variable description​

Docker Compose​

Troubleshooting​

When monitoring data is not visible​

Step 1: Check environment variables​

Step 2: Check agent execution​

Step 3: Check network​

When instrumentation is not applied​

Check detailed instrumentation logs​

Common issues and solutions​

Additional support​