Instrumentation and Code Coverage#

Introduction#

Antithesis can be configured to capture a code coverage metric for your system as it runs under our tests. The way we do this is through a process called “instrumentation,” whereby we add special callbacks to every important point in your code. The way we do this is a little different for every language, but each way produces a common output formatting, enabling us to provide unified reporting across your entire architecture.

Benefits of Instrumentation#

Code coverage reporting is not the only reason to enable instrumentation. There are several other benefits:

  • Instrumentation enables us to surface data in the Triage Report about which files and functions were covered in any given test run. This can help to identify gaps in coverage, or ways to improve a workload.

  • Instrumentation allows us to support Sometimes Assertions that refer to specific lines of code or conditions in your code.

  • Instrumentation provides much richer data to the Bug Report, allowing us to automatically discover which lines of code were most and least associated with the bug.

  • Instrumentation activates a powerful fault-injection technique called thread pausing which can quickly find even the rarest and most subtle race conditions, and other concurrency bugs.

  • Instrumentation sends continuous feedback to the Antithesis platform which enables it to find bugs faster and more reliably.

Supported Languages#

The following is a list of languages that are supported for instrumentation and code coverage.

If your language is not on this list, it may still be possible to enable instrumentation. Contact us for more details.

Symbolization#

Symbolization is the process of translating between locations in your compiled code and locations in your source files. For some languages, the Antithesis platform handles all of this automatically. For other languages, we require your build/CI system to put symbol files into a specific location in order for symbolization to work.

Antithesis will search the root of every container image you push for a directory named /symbols and automatically extract any symbol files it finds there. When searching for symbol files, Antithesis will follow symlinks. In general, symbols are placed in the image containing the instrumented software. Howevever, on rare occasion the resulting images will be so large as to impact test performance. In this case, you can instead place the symbols in the config image.

Please consult the language-specific documentation for detailed instructions on enabling symbolization. Symbol files from multiple programs, containers, or microservices can be combined into the same config image.

Validation#

You can confirm that the instrumentation process worked correctly by looking at your triage report. Specifically, under the Setup property group, there is a default property called Software was instrumented. If this property is passing, then your code was instrumented successfully and we were able to symbolize it as well. Each example listed under this property is a different binary, program, or module that was successfully instrumented. The details section for the examples will list the name of the module and the number of locations within it that were instrumented.