Basic usage

whatap-go-inst is a CLI tool that automatically inserts monitoring code during build. You can add WhaTap monitoring to Go applications without directly modifying source code.

This document guides you through the installation and basic usage of whatap-go-inst.

Tip

To add monitoring code by directly using the API, see the Manual instrumentation guide.

Support environment

To use whatap-go-inst, the following environment is required.

Item	Requirements	Note
Go version	1.18 or later	Required when building instrumented code
OS	Linux	amd64, arm64

Note

The whatap-go-inst binary can run without Go installation. However, Go 1.18 or later is required to build instrumented code.

Quick start

Step 1: Install whatap-go-inst

There are 3 ways to install whatap-go-inst. Choose the method that suits your environment.

Go install installation (Recommended)

This is the recommended installation method for Go 1.21 or later.

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

Direct binary installation

This is a method to install directly without Go installation. Users of Go 1.18-1.20 should use this method.

# 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/

Build from source

git clone https://github.com/whatap/go-api-inst.git
cd go-api-inst
go build -o whatap-go-inst .

Step 2: Build and run

# Build with monitoring code automatically inserted
whatap-go-inst go build ./...

# Run
./myapp

Done!

You can now check data in WhaTap Monitoring Service.

💡 Don't want to change the original code at all?

Using wrap mode, you can build without changes to whatap_inst.tool.go file or go.mod.

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

Wrap mode features

• No changes to original project files
• Useful for initial testing or temporary application
• Requires --wrap option every time

---

whatap-go-inst detailed explanation

How it works

whatap-go-inst analyzes source code during build and automatically inserts monitoring code.

1. main() function initialization

// Before change
func main() {
    // Application code
}

// After change
func main() {
    trace.Init(nil)         // Automatically added
    defer trace.Shutdown()  // Automatically added
    
    // Application code
}

2. Web framework middleware

// Before change
r := gin.Default()
r.GET("/api", handler)

// After change
r := gin.Default()
r.Use(whatapgin.Middleware())  // Automatically added
r.GET("/api", handler)

3. Database calls

// Before change
db, _ := sql.Open("mysql", dsn)

// After change
db, _ := whatapsql.Open("mysql", dsn)  // Automatically changed

Main supported libraries

• Web frameworks: Gin, Echo, Fiber, Chi, Gorilla Mux, net/http, FastHTTP
• Databases: database/sql, sqlx, GORM v1/v2
• Cache/NoSQL: Redis (go-redis, Redigo), MongoDB
• External services: gRPC, Kafka (Sarama), Kubernetes client-go
• Logging: log, logrus, zap

View complete list of supported libraries

Category	Supported libraries
Web frameworks	Gin, Echo v4, Fiber v2, Chi v5, Gorilla Mux, net/http, FastHTTP
Databases	database/sql, sqlx, GORM v1/v2
Redis	go-redis v8/v9, Redigo
NoSQL	MongoDB
Message queue	Kafka (Sarama - IBM/Shopify)
RPC	gRPC
Kubernetes	client-go
Logging	log, logrus, zap

---

Commands

Category	Command	Description	Main usage
Basic	whatap-go-inst go build	Build with monitoring code inserted	Normal build
Basic	whatap-go-inst go run	Run with monitoring code inserted	Development/Test
Basic	whatap-go-inst go test	Test with monitoring code inserted	Unit test
Advanced	whatap-go-inst inject	Output instrumentation code to separate directory	Code review
Advanced	whatap-go-inst remove	Remove inserted monitoring code	Uninstrument
Utility	whatap-go-inst version	Check version	Version check

Tip

After whatap-go-inst go, you can use it the same way as regular go commands.

# Example: Use like regular go commands
whatap-go-inst go build -o myapp -ldflags="-s -w" .

Main options

whatap-go-inst go options

Option	Description
--error-tracking	Insert error tracking code (add trace.Error to if err != nil pattern)

Usage examples:

# Wrap mode
whatap-go-inst go --wrap build ./...

# Include error tracking
whatap-go-inst go --error-tracking build ./...

inject/remove options

Option	Description
-s, --src	Source code path
-o, --output	Output directory
--all	(remove only) Also attempt to remove manual insertion patterns

Usage examples:

# Save instrumentation code separately
whatap-go-inst inject -s ./src -o ./instrumented

# Remove instrumentation code
whatap-go-inst remove -s ./instrumented -o ./clean

Global options

Common options that can be used with all commands.

Option	Description
--verbose, -v	Verbose output (display conversion details per file)
--quiet, -q	Output summary only
--config	Configuration file path (default: .whatap/config.yaml)
--report	JSON report file path

Usage examples:

# Verbose output
whatap-go-inst -v go build ./...

# Specify configuration file
whatap-go-inst --config ./my-config.yaml go build ./...

---

Frequently asked questions

Will the original code be changed?

The original code is not modified. whatap-go-inst copies source code to a tmp directory, downloads dependencies, and builds.

Build output is generated in the whatap-instrumented directory.

What's different from existing go commands?

whatap-go-inst go build works the same as regular go build, but automatically inserts monitoring code before building. All options and flags can be used as is.

# Use the same as regular build commands
whatap-go-inst go build -o myapp -ldflags="-s -w" .

Will build time slow down?

Build time takes longer than a normal build due to copying to tmp directory, downloading dependencies, and code insertion.

It seems instrumentation is not being applied?

Check the following:

# Delete build cache and rebuild
go clean -cache
whatap-go-inst go build ./...

# Check detailed logs in debug mode
GO_API_AST_DEBUG=1 whatap-go-inst go build ./...

For more details, see the Automatic instrumentation guide.

Can it be used in Docker environment?

Yes, you can use it the same way in Dockerfile:

FROM golang:1.21 AS builder

WORKDIR /app

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

# Copy source
COPY . .

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

FROM alpine:latest
COPY --from=builder /app/myapp /app/myapp
CMD ["/app/myapp"]

For more details, see the Docker installation guide.