Go instrumentation

The Go instrumentor is a command-line tool which transforms your source code to enable full SDK functionality when running in the Antithesis environment. The instrumentor provides assertion cataloging and coverage instrumentation.

• Assertion cataloging: The instrumentor modifies your program so that at runtime it emits a catalog entry for every assertion you define (like Always(), Sometimes(), Unreachable(), etc.) Assertion cataloging is necessary for certain assertions to work.

• Coverage instrumentation: The instrumentor adds coverage callbacks at every basic block in the program’s control flow and writes the transformed source files to a separate directory. These callbacks enable the Antithesis platform to test your program more effectively.

The Go instrumentor transforms Go language code during compilation with a “toolexec” tool that wraps the go build’s compile and link steps. If your workflow is already relying on an incompatible “toolexec” wrapper or does not use go build, please refer to the legacy process documentation for an alternative. We’re happy to work with you to determine the best way to integrate the Go instrumentor into your build system. If you need help with this, contact us at support@antithesis.com or ask on our Discord.

The Go instrumentor is distributed as part of the Antithesis Go SDK.

Setup

Install the instrumentor as follows:

1. Add the Antithesis SDK for Go to your Go module and install the instrumentor tool.

go get github.com/antithesishq/antithesis-sdk-go@latest
go install github.com/antithesishq/antithesis-sdk-go/tools/antithesis-go-toolexec@latest
go mod tidy

2. Ensure you can run the tool.

antithesis-go-toolexec --help

Using the instrumentor

The instrumentor may be run in three modes:

1. Coverage instrumentation and assertion cataloging mode, which is the default.
2. Assertion cataloging only mode, where an environment variable restricts the tool to only catalog assertions.
3. Coverage instrumentation only mode, where an environment variable restricts the tool to only add coverage callbacks.

The syntax and a short description of each mode follows. To see an overview of this tool, run antithesis-go-toolexec --help.

To configure the options when running the instrumentor tool, checkout the common instrumentation options.

Default mode

Add -toolexec=antithesis-go-toolexec to the build command you already use to use the tool. In the examples that follow, we build ./cmd/app to /app.

go build -toolexec=antithesis-go-toolexec -o /app ./cmd/app

Or if you don’t want to change the build command, you can use environment variable instead:

ENV GOFLAGS=-toolexec=antithesis-go-toolexec
RUN go build -o /app ./cmd/app
RUN go test ./...                      # instrumented too

Coverage instrumentation only mode

To turn off cataloging:

ANTITHESIS_SKIP_CATALOG=1 go build -toolexec=antithesis-go-toolexec -o /app ./cmd/app

Cataloging only mode

To turn off coverage instrumentation:

ANTITHESIS_SKIP_COVERAGE=1 go build -toolexec=antithesis-go-toolexec -o /app ./cmd/app

Common instrumentation options

You can configure options using environment variables.

ANTITHESIS_SKIP_COVERAGE
Specify true to skip coverage instrumentation.

ANTITHESIS_SKIP_CATALOG
Specify true to skip assertion cataloging.

ANTITHESIS_VERBOSE
Verbosity level 0-3, where 3 is highest. Logs to stderr during the build.

ANTITHESIS_INSTRUMENT
Comma-separated import path prefixes to instrument. By default, it includes everything whose sources are in the working tree and excludes downloaded dependencies.

ANTITHESIS_EXCLUDE
The full path to a text file that lists the files and directories to exclude from being scanned by the Go instrumentor. Excluded files and directories will not be instrumented and their assertions will not be cataloged. By default all the .go files in a Go module will be cataloged, and the instrumentor ignores all directories beginning with a .

The exclusion file must contain paths to the files or directories to exclude — these paths are relative to the Go project directory. The entries must be newline separated. Lines beginning with a ”#” are ignored, and so are all-whitespace lines. One exclusion file might be:

new_feature.go
# This line does nothing
mypack/newstuff

Every file or directory that you attempt to exclude must exist. If you attempt to exclude nonexistent files or directories, the instrumentor will fail.

ANTITHESIS_SYMBOLS_DIR
The full path to the directory where symbols tables are collected. The default directory is /symbols.

ANTITHESIS_SYMBOL_PREFIX
The prefix for symbol table file names.

ANTITHESIS_SKIP_TEST_FILES
Specify true to have the instrumentor ignore all files that end with _test.go.