Causality analysis

The causality analysis report helps you identify the underlying causes of a bug. It shows you which events in your system are associated with the bug becoming more likely to happen.

How causality analysis works

Causality analysis takes a single timeline where we saw the bug and rewinds time to different moments.

For a given moment, it explores forwards again multiple times with different fuzzer behavior. This can include:

different patterns of faults
different patterns of test commands
different workload behavior (if your workload uses randomness)
different thread and process scheduling

It then sees how many timelines hit the bug again.

This information is then summarized in a graph of bug probability over time.

Example: coin flips

As an illustrative example, take a program that simulates flipping two coins one after another, and then checks the result later. If both coins come up heads, we count it as a bug.

We take a single timeline where we saw this bug and rewind time to different points. From each point, we let Antithesis explore forward multiple times and see if we still hit the bug. Putting all this information together gives us a graph of bug probability against time. Here’s the graph, with the coin flips labelled:

Causality analysis for the coin flip example. There are sharp vertical jumps at the points that coin flips occur.

To understand this graph, it’s easiest to work backwards from the bug from the latest time:

If you rewind to a point after the second flip, you know that both coins came up heads. At this point the bug is “baked in”: you’re guaranteed to see it when you check, and so the probability is 100%.
If you rewind to somewhere between the first and second flip, you know that the first coin came up heads. But as Antithesis explores forwards again, the second coin flip could be either heads or tails, leading to a bug probability of roughly 50%.
If you rewind to before the first flip, each coin flip could be either heads or tails, leading to a bug probability of roughly 25%.

The coin flips stand out as two sharp jumps in the bug probability.

Below the graph, you’ll see the logs for the original bug timeline, filtered for the time window that you’re currently viewing. You can use the logs to investigate what’s happening around the time of the jump.

How to use the report

When reading the graph, a few things are worth keeping in mind:

Look out for sharp upward jumps in the bug probability and check the logs around these points. Jumps like this are a strong signal that something interesting is happening at those points (like the coin flips in the example above).
You may see parts of the graph where the probability goes down. This may seem unintuitive but can occur for a number of reasons. For example, you might have a situation where the bug is easy to trigger for some stretch of time, then gets hard to trigger, then gets easy again. If you detect the bug in the second easy stretch and run causality analysis, you’ll see a graph where the probability goes down during the hard stretch. In these situations, you may find an easier-to-interpret graph by running causality analysis on a different example of the same bug. In particular, examples where the bug occurs earlier in its timeline may be easier to interpret.
If you use test commands, one reason the probability can go down is if the bug is only triggered by a specific type of command. This command type will not necessarily be run in every timeline (especially if it is an eventually or finally command). You may be able to solve this by moving an assertion into an anytime command, which can cause it to run more often.

How to generate a causality analysis report

You can generate a causality analysis report from a specific bug example in the Properties section of the triage report:

Examples of a bug in the triage report, with 'Causality analysis' button.

To generate the report, select Causality analysis for the example you’re interested in. Give your report a description, and optionally add email addresses. Then select to generate the report.

To view your report, go to the Debugging sessions view. Once results start streaming, you will see your report in the list. Click on it to watch the graph update in real time. If you provided an email address, you will also get the final report emailed to you once streaming finishes.