Rust instrumentation

Prerequisites

The instrumentation process depends on an Antithesis provided library, libvoidstar.so, which can be found here. We recommend downloading and vendoring it into your source repo or otherwise caching it, so that the success of your builds does not inadvertently depend on the uptime of our website.

This library will become a dynamic runtime dependency of your instrumented program. Your program will need to be able to find this library in order to run successfully, both within the Antithesis environment, and in local testing. Your container building process must install this library at /usr/lib/libvoidstar.so, and your system must be configured so that this location is on your library search path.

Build Requirements

To enable instrumentation for your code, you’ll need to compile your binary using a modern version of Cargo, and the following compile flags:

LD_LIBRARY_PATH=${PATH_TO_LIBVOIDSTAR} 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  \
    -L${PATH_TO_LIBVOIDSTAR} \
    -lvoidstar" \
    cargo build --bin $BINARY_NAME

Validation

Once the binary has been compiled, verify that it has correctly linked to the Antithesis runtime library.

Run the command ldd {binary} to identify its runtime dependencies, and a grep of the string “libvoidstar” to confirm the location of the shared object.

$ ldd client_binary | grep "libvoidstar"
libvoidstar.so => /usr/lib/libvoidstar.so

To confirm that the instrumentation process was successful, you should also run the command nm to list all the symbols in the binary, and a grep of the string “sanitizer_cov_trace_pc_guard”.

$ nm client_binary | grep "sanitizer_cov_trace_pc_guard"
U __sanitizer_cov_trace_pc_guard
U __sanitizer_cov_trace_pc_guard_init

Notice the “U” character in the previous code block: it means the symbol is (U)ndefined, and the program needs to retrieve the symbol from a library. The instrumented program now looks for this symbol in our runtime library.

If the symbol is not “U”, you may see the character(s) “W” or “T”. Most likely, the binary is not linking to our library but linking to a statically included copy of the Clang runtime library. This may happen if you add fsanitize-coverage-trace-pc-guard to -Clink-args in addition to Cllvm-args.

It is also possible that -fsanitize-coverage=trace-pc-guard was added to your compile flags AND to your link flags. In order for instrumentation to work, it must only be in your compile flags.

Symbolization

The LLVM compiler infrastructure will output debug symbols in the 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.

Help

Contact us if you need help with this.