Causality analysis

The causality analysis report helps you understand the cause of a specific bug by showing you which events in your system are associated with the bug becoming more likely.

To generate the report, Antithesis rewinds the simulation to different times before the bug happens and tries new sequences of events to see whether the bug occurs or not. The causality analysis graph in the report summarises these results by showing you bug probability over time.

To see how the graph works, we’ll use a toy example of 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 the 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:

To interpret this graph, it’s easiest to work backwards from the bug:

• 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. Jumps like this are a strong signal that something interesting is happening at those points.

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 generate a causality analysis report

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

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.