Configuration guide

This guide explains how to control instrumentation behavior using whatap-go-inst configuration files and environment variables. You can easily configure using Presets or finely control by selecting individual packages.

For basic usage, see Basic usage first.

Configuration file

File location

Configuration files are searched in the following order.

Priority	Location	Description
1	--config flag	whatap-go-inst --config=/path/to/config.yaml
2	WHATAP_INST_CONFIG environment variable	WHATAP_INST_CONFIG=/path/to/config.yaml
3	.whatap/config.yaml	.whatap directory in project root (Recommended)
4	.whatap/whatap.yaml	Alternative filename

Tip

It is recommended to create and use a .whatap/config.yaml file in the project root.

Basic structure

# .whatap/config.yaml
instrumentation:
  preset: "full"           # Preset selection (full/minimal/web/database/external/log/custom)
  error_tracking: false    # Whether to enable error tracking
  enabled_packages: []     # Additional packages to enable
  disabled_packages: []    # Packages to disable

exclude:                   # Instrumentation exclusion patterns (optional)
  - "**/*_test.go"

---

Configuration items

Preset options

You can easily select package groups to instrument using Presets.

Preset	Included items	Description
full (Default)	Web + Database + External services + Log	Activate all packages
minimal	trace.Init/Shutdown	Minimal configuration (excluding framework middleware)
web	Gin, Echo, Fiber, Chi, Gorilla Mux, net/http, FastHTTP	Web frameworks only
database	database/sql, sqlx, GORM v1/v2	Databases only
external	Redis, MongoDB, Kafka, gRPC, Kubernetes	External services only
log	log, logrus, zap	Log libraries only
custom	Directly specify with enabled_packages	User-defined

Preset combination

You can finely control by combining Presets and package options.

Final enabled packages = Preset packages + enabled_packages - disabled_packages

Combination examples:

• preset: full + disabled_packages: ["grpc"] → Full except gRPC
• preset: web + enabled_packages: ["sql"] → Web frameworks + SQL
• preset: custom + enabled_packages: ["gin", "sql"] → Only Gin and SQL

Environment variables

You can also configure using environment variables instead of configuration files.

Environment variable	Description	Value	Default
GO_API_AST_DEBUG	Enable debug output	1 (enable), 0 (disable)	0
GO_API_AST_OUTPUT_DIR	Instrumented source output directory	Directory path	-
WHATAP_INST_CONFIG	Configuration file path	File path	.whatap/config.yaml

Configuration priority

Configuration values are applied in the following order.

CLI options > Environment variables > Configuration file > Default values

Source	Example	Priority
CLI options	--error-tracking	1 (Highest)
Environment variables	GO_API_AST_DEBUG=1	2
Configuration file	error_tracking: true	3
Default values	false	4 (Lowest)

File exclusion patterns

Specify file patterns to exclude from instrumentation.

Default exclusion patterns

If you don't specify exclude patterns in the configuration file, the following patterns are automatically applied:

Pattern	Description
**/*.pb.go	protobuf generated files
**/*.pb.gw.go	grpc-gateway generated files
**/*_grpc.pb.go	grpc generated files
**/*.connect.go	connect-go generated files
**/*_generated.go	Auto-generated files
**/*_gen.go	Code generator output
**/*_test.go	Test files
vendor/**	vendor directory
.git/**	git directory
node_modules/**	node_modules directory
whatap-instrumented/**	Instrumented output directory

Note

Exclusion reasons

• Generated code (protobuf, grpc, etc.): May cause compilation errors
• Test files: Unnecessary for production monitoring
• Dependency directories: Third-party code

Custom exclusion patterns

Specifying exclude patterns replaces the default values.

# .whatap/config.yaml
exclude:
  - "**/*_test.go"
  - "vendor/**"
  - "internal/legacy/**"    # Exclude legacy code
  - "migrations/**"          # Exclude migration files

Glob pattern syntax

Pattern	Description	Match example
*	All characters in filename	*.go → main.go
**	Recursively all directories	**/test/** → a/b/test/c/d.go
?	Single character	test?.go → test1.go
[abc]	Character class	test[12].go → test1.go

Copy exclusion directories (copy_exclude)

In wrap mode (whatap-go-inst go build), specify directories to exclude when copying source files to a temporary directory.

Default exclusion directories

The following directories are automatically excluded:

Directory	Description
.git	Git repository
.svn	SVN repository
.hg	Mercurial repository
node_modules	Node.js dependencies
vendor	Go vendor directory
.idea	JetBrains IDE settings
.vscode	VS Code settings
whatap-instrumented	Instrumented source output

Note

build and dist directories are not excluded by default as they are often used as go:embed targets in Go projects.

Custom exclusion directories

# .whatap/config.yaml
copy_exclude:
  - "tmp"           # Temporary directory
  - "cache"         # Cache directory
  - "data"          # Large data directory
  - "testdata"      # Test data

Tip

Custom copy_exclude items are added to the default list (not replaced).

exclude vs copy_exclude differences

Option	Purpose	Applied at
exclude	File patterns to exclude from instrumentation	During AST analysis
copy_exclude	Directories to exclude from copying	During wrap mode file copy

• exclude: Exclude specific files using glob patterns like _test.go, **/*.pb.go
• copy_exclude: Exclude entire directories by directory name like tmp, cache

Log collection

To enable log collection, configure as follows.

# .whatap/config.yaml
instrumentation:
  preset: "full"  # Include log packages

# whatap.conf
logsink_enabled=true

Note

• When instrumented with whatap-go-inst, TraceLogWriter is automatically inserted
• Transaction ID(@txid), multi-transaction ID(@mtid), etc. are automatically included in logs
• TraceLogWriter method is recommended (transaction linkage possible)

---

Configuration examples

Enable all

# .whatap/config.yaml
instrumentation:
  preset: "full"

All supported packages are enabled.

Web and database only

# .whatap/config.yaml
instrumentation:
  preset: "custom"
  enabled_packages:
    - "gin"
    - "echo"
    - "sql"
    - "gorm"

Only Gin, Echo, database/sql, and GORM are instrumented.

Exclude specific packages

# .whatap/config.yaml
instrumentation:
  preset: "full"
  disabled_packages:
    - "k8s"
    - "grpc"

All packages except Kubernetes and gRPC are instrumented.

Enable error tracking

# .whatap/config.yaml
instrumentation:
  preset: "full"
  error_tracking: true

trace.Error(ctx, err) code is automatically inserted into if err != nil patterns.

// Before change
if err != nil {
    return err
}

// After change
if err != nil {
    trace.Error(ctx, err)  // Automatically added
    return err
}

Environment-specific configuration files

# Development environment
WHATAP_INST_CONFIG=.whatap/dev-config.yaml whatap-go-inst go build ./...

# Production environment
WHATAP_INST_CONFIG=.whatap/prod-config.yaml whatap-go-inst go build ./...

# .whatap/dev-config.yaml
instrumentation:
  preset: "full"
  debug: true
  error_tracking: true

# .whatap/prod-config.yaml
instrumentation:
  preset: "full"
  error_tracking: true
  debug: false

Debug mode

# .whatap/config.yaml
instrumentation:
  debug: true
  preset: "full"

Detailed debug information is output during build.

[whatap-go-inst] Config file: .whatap/config.yaml
[whatap-go-inst] Preset: full
[whatap-go-inst] Processing: main.go
[whatap-go-inst]   Added: trace.Init
...

Instrumentation code output

# .whatap/config.yaml
instrumentation:
  output_dir: "./instrumented"
  preset: "full"

Instrumented source code is saved to the ./instrumented directory.

Use cases:

• Review instrumentation results
• Analyze instrumentation code in CI/CD

---

Troubleshooting

When instrumentation is not 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 ./...

When compilation errors occur

Auto-generated files like protobuf may be instrumented causing errors. Check the exclude patterns:

# .whatap/config.yaml
exclude:
  - "**/*.pb.go"
  - "**/*_generated.go"

When wrap mode build is slow

Add large directories to copy_exclude:

# .whatap/config.yaml
copy_exclude:
  - "data"
  - "testdata"
  - "tmp"

Complete list of supported packages

Web frameworks

Package name	Library	Inserted code
gin	github.com/gin-gonic/gin	whatapgin.Middleware()
echo	github.com/labstack/echo/v4	whatapecho.Middleware()
fiber	github.com/gofiber/fiber/v2	whatapfiber.Middleware()
chi	github.com/go-chi/chi/v5	whatapchi.Middleware
gorilla	github.com/gorilla/mux	whatapmux.Middleware
nethttp	net/http	whataphttp.Func(), whataphttp.Handler()
fasthttp	github.com/valyala/fasthttp	whatapfasthttp.Middleware()

Databases

Package name	Library	Inserted code
sql	database/sql	whatapsql.Open()
sqlx	github.com/jmoiron/sqlx	whatapsqlx.Open()
gorm	gorm.io/gorm	whatapgorm.Open()
jinzhugorm	github.com/jinzhu/gorm	whatapgorm.Open()

External services

Package name	Library	Inserted code
redigo	github.com/gomodule/redigo	whatapredigo.Dial()
goredis	github.com/redis/go-redis/v9	whatapgoredis.NewClient()
mongo	go.mongodb.org/mongo-driver	whatapmongo.Connect()
sarama	github.com/IBM/sarama	Kafka Interceptor
grpc	google.golang.org/grpc	Server/Client Interceptor
k8s	k8s.io/client-go	config.Wrap()

Log libraries

Package name	Library	Inserted code
log	log	log.SetOutput(logsink.GetTraceLogWriter())
logrus	github.com/sirupsen/logrus	logrus.SetOutput(logsink.GetTraceLogWriter())
zap	go.uber.org/zap	logsink.HookStderr()