Troubleshooting

This guide provides troubleshooting steps for issues that may occur when using whatap-go-inst.

When instrumentation is not applied

Step 1: Clear build cache

# Clear build cache
go clean -cache

# Rebuild
whatap-go-inst go build ./...

Step 2: Check debug mode

# Check instrumentation process with debug output
GO_API_AST_DEBUG=1 whatap-go-inst go build ./...

---

Common problem solving

Specific files not instrumented

Cause:

• File is included in exclusion pattern
• Generated code files (*.pb.go, *_generated.go, etc.)

How to check:

# Check skipped files
GO_API_AST_DEBUG=1 whatap-go-inst go build ./... 2>&1 | grep "SKIP"

Solution:

Adjust exclusion patterns or remove exclusion for specific files. For more details, see Configuration guide - Exclusion patterns.

---

Build succeeds but no data visible

1. Check agent execution

ps -ef | grep whatap_agent

If not present:

# Start agent
/usr/whatap/agent/whatap_agent -d

2. Check main() initialization

# Check if trace.Init is in main() function
GO_API_AST_DEBUG=1 whatap-go-inst go build ./... 2>&1 | grep "trace.Init"

3. Check whatap.conf configuration

cat /usr/whatap/agent/whatap.conf

Required configuration:

license={access key}
whatap.server.host={collection server IP}

---

No instrumentation in Docker environment

Problem: whatap-go-inst not installed in multi-stage build

Solution:

FROM golang:1.21 AS builder

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

# Initialize and build
COPY . .
RUN whatap-go-inst go build -o /app/myapp .

For more details, see Docker installation guide.

---

Execution mode comparison

whatap-go-inst provides multiple execution modes. Choose the mode that fits your situation.

Mode comparison table

Mode	Command	Original changes	Auto dependency	Recommended use
default wrap mode	whatap-go-inst go build	❌	✅	Recommended
inject mode	whatap-go-inst inject	Separate output	❌	Code review/CI

default wrap mode (recommended)

# Build directly without init
whatap-go-inst go --wrap build ./...

Features:

• ✅ No changes to original files at all
• ✅ Modified files are saved to ./whatap-instrumented. Easy error analysis.

Use cases:

• Selective instrumentation in CI/CD

---

inject mode

# Output instrumented code to separate directory
whatap-go-inst inject -s ./src -o ./instrumented

# Build with output code
cd instrumented
go build ./...

Features:

• ✅ Save instrumented code separately
• ✅ Can compare original and instrumented code
• ⚠️ Requires manual dependency installation
• ⚠️ Requires inject execution before build

Use cases:

• Review instrumentation results
• Pre-instrumentation in CI/CD pipeline
• Check diff between original and transformed code

---

Migrating from go-api

How to migrate a project that directly uses go-api to whatap-go-inst.

Step 1: Remove existing whatap code

# Remove only automatic insertion patterns
whatap-go-inst remove -s . -o ./cleaned

# Also attempt to remove manual insertion patterns
whatap-go-inst remove --all -s . -o ./cleaned

Step 2: Check changes

# Check differences with diff
diff -r . ./cleaned

# Or git diff
cp -r ./cleaned/* .
git diff

Step 3: Restore custom code

Manually restore patterns not removed by remove --all or necessary custom code.

// Example: Keep custom transaction code
ctx, _ := trace.Start(context.Background(), "CustomTx")
defer trace.End(ctx, nil)

Step 4: Build with whatap-go-inst

whatap-go-inst go build ./...

Caution

Patterns not automatically removed:

• Variable assignment: ctx := trace.Start(...)
• Closure pattern: whatapsql.Wrap(...)
• Complex custom instrumentation

These patterns will show warning messages and must be removed manually.

Additional support

If not resolved by the above methods:

1. Collect debug logs

   GO_API_AST_DEBUG=1 whatap-go-inst go build ./... > debug.log 2>&1

2. Collect environment information

   go version
   whatap-go-inst version
   cat .whatap/config.yaml

3. Contact WhaTap Support Center
   • Debug logs
   • Environment information
   • Reproducible minimal example

Still not resolved?

If it cannot be handled with basic instrumentation, see Custom instrumentation.