> ## Rust instrumentation

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

---

This page covers how to enable coverage instrumentation for a Rust binary you plan to run in Antithesis. You'll add a crate, reference it once in your code, and pass a handful of build flags. Find the crate [here](https://crates.io/crates/antithesis-instrumentation).

If you enabled rust instrumentation before May 22, 2026, you're probably using the [legacy method](/docs/reference/sdk/rust/legacy_instrumentation/). We recommend switching to this method when you can, for now the other method is still supported.

## Step 1: Add the dependency to Cargo.toml

```toml
[dependencies]
antithesis-instrumentation = "0.1"
```

> **Note**
>
> Check [crates.io](https://crates.io/crates/antithesis-instrumentation) for the latest version.

## Step 2: Include a reference to the library in your code

Somewhere in your Rust code, add this line at least once:

```rust
use antithesis_instrumentation as _;
```

Without it, Cargo treats the crate as unused and the linker drops the runtime shim. You can include this line in any Rust file in your project, it doesn't matter which. You may also want to put this under a `#[cfg]`.

## Step 3: Adjust your build flags

There are two ways to do this: either at the command line or via a .toml file. You can pick either; you don't need to do both.

### Option A: Build flags at the command line

You'll need to specify the --config options below. Your full command line will look something like this:

```bash
cargo build --bin main \
    --config 'build.target = "x86_64-unknown-linux-gnu"' \
    --config 'target.x86_64-unknown-linux-gnu.rustflags = [
        "-Ccodegen-units=1",
        "-Cpasses=sancov-module",
        "-Cllvm-args=-sanitizer-coverage-level=3",
        "-Cllvm-args=-sanitizer-coverage-trace-pc-guard",
        "-Clink-args=-Wl,--build-id",
    ]'
```

### Option B: Build flags in a .toml file

You can put the flags into .cargo/config.toml file instead like this:

```toml
[build]
target = "x86_64-unknown-linux-gnu"

[target.x86_64-unknown-linux-gnu]
rustflags = [
    "-Ccodegen-units=1",
    "-Cpasses=sancov-module",
    "-Cllvm-args=-sanitizer-coverage-level=3",
    "-Cllvm-args=-sanitizer-coverage-trace-pc-guard",
    "-Clink-args=-Wl,--build-id",
]
```

> **Note**
>
> LLVM-instrumented binaries must have GNU build ids for symbolization to work. As long as you use the `-Clink-args=-Wl,--build-id` flag above, you'll be fine.

## Validation

To confirm that the instrumentation process was successful, you'll check two things:

1. You included the instrumentation crate in your code.
2. Your binaries are actually instrumented.

To check if you've included the instrumentation crate, run the command `nm` to list all the symbols in a binary, and then grep the string “antithesis\_load\_libvoidstar”.

```shell frame="none"
$ nm client_binary | grep "antithesis_load_libvoidstar"
T antithesis_load_libvoidstar
```

Notice the “T” character in the previous code block: it means the symbol is in the text (code) section.

To check that you've correctly built the binaries with the right flags. Run the command `readelf` and grep the string "sancov".

```shell frame="none"
$ readelf -S target/x86_64-unknown-linux-gnu/debug/main | grep sancov
[31] __sancov_guards   PROGBITS        00000000000649c0 0649c0 000030 00  WA  0   0  4
```

If you built your binaries correctly, you'll see something similar, but the addresses may be different.

## Symbolization

The LLVM compiler infrastructure will output debug symbols in the [DWARF](https://en.wikipedia.org/wiki/DWARF) format. They could be separate debug info or just the original unstripped binary. These files should be symlinked (or moved) into a directory named `/symbols` in the root of the [appropriate container image](/docs/reference/instrumentation/coverage_instrumentation/#symbolization).

## Help

If you need help with this, write to us at [support@antithesis.com](mailto:support@antithesis.com) or talk to your forward deployed engineer.