> ## Go instrumentation

> Fetch the complete documentation index at: https://antithesis.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---

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](https://antithesis.com/docs/generated/sdk/golang/assert/) 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](/docs/product/writing_tests/instrumentation/coverage_instrumentation/).

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](/docs/reference/sdk/go/legacy_instrumentation/) 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](mailto:support@antithesis.com) or [ask on our Discord](https://discord.com/invite/antithesis).

> **Note**
>
> When you compile your application to run in Antithesis, cgo must be enabled (`CGO_ENABLED=1`) and a C compiler (such as `clang` or `gcc`) must be available. If you build with `CGO_ENABLED=0`, the SDK cannot report to Antithesis: assertions, lifecycle events, and coverage are all lost. The instrumentor tool itself does not require cgo; this applies only to building the instrumented program.

The *Go instrumentor* is distributed as part of the Antithesis [Go SDK](/docs/reference/sdk/go/).

## Setup

Install the instrumentor as follows:

1. Add the [Antithesis SDK for Go](https://github.com/antithesishq/antithesis-sdk-go) to your Go module and install the instrumentor tool.

```bash
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
```

> **Note**
>
> These examples use the (generally recommended) version called `latest`. You might choose a specific version such as `v0.2.7`.

2. Ensure you can run the tool.

```bash
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](#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`.

```bash
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:

```bash
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:

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

## Cataloging only mode

To turn off coverage instrumentation:

```bash
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`.