Visual debugging with AppLand

Overview

Software engineers use AppLand to capture detailed snapshots of their application’s code execution and data pathways. AppLand provides a simple interface to navigate and analyze these snapshots, giving users the ability to rapidly identify erroneous or unexpected behaviors. Snapshots can be shared with a colleague or attached to a bug report to provide an unparalleled level of detail, thereby expediting the bug resolution process. Finally, a browser extension allows users to capture snapshots directly from within the browser.

This document will outline how to record a live instance of your own application and analyze the results.

Prerequisites

  1. The AppMap recording client has been installed into your application successfully. If you've not yet completed this step, follow the instructions for Ruby or Java.
  2. The AppLand browser extension is installed in your browser. If you do not yet have the extension installed, find it here for either Chrome or Firefox. For more detailed instructions, see the documentation for the AppLand browser extension.

Create a recording

First, identify a behavior of interest to record within your application. Any interaction which issues a request that is processed by the backend will work. Navigate to the application you wish to record, open the browser extension window and click "Record" .

Once the recording has begun, perform an interaction to trigger some behavior in the backend. Once the request has been processed and a response has been received, return to the browser extension window and click "Stop recording". This will pop open a new tab to AppLand containing a visualization of the data captured.

Analyzing the scenario

Execution flow

There's no need to manually step through your code to build a mental model of its execution and data flow. Use AppLand to navigate a holistic mapping of your application's execution and drop into source code where necessary.

The call tree flows from left to right, top to bottom. When a function makes a call to another function, it will have an outbound link from left to right. Additional function calls from the same caller will flow downwards. In the example below, Main calls two functions: Process and Execute in their respective order.

Try using the arrow buttons above to walk the call stack. Similar controls can be found in the scenario view at the top of the "Timeline" panel.

Data flow and details

AppLand keeps a record of every argument passed into and returned from a function call. This information can be used to identify incorrect parameters, mutations and data flow. Trace values back to their origin or follow their propagation through the call stack.

In the Scenario view, a function call can be selected to display additional details in the right side panel. Use this window to see function arguments, return values, SQL and exceptions. You can also click on a value port to see the value it contains. Colored links connect two ports where values are passed from one function to another.

Try clicking on a value port to see the value recorded.

SQL queries

When it comes to database queries, it's not always clear what queries are being executed from where. This is especially true when constructing queries programmatically through an abstraction layer such an ORM. AppLand records SQL queries as they're executed, capturing a detailed context about the query and its surrounding application logic and data flow. Use this view to identify unexpected calls, queries, parameters or results.

Exceptions

AppLand depicts functions which exit early due to an exception. Bugs introduced during exception handling can oftentimes be hard to spot, especially when an exception is silently handled in an unexpected location. Use this view to easily identify and trace an exception from its origin its handler.

Exceptions are indicated by a symbol in the top right of a function call.

Practice testing your mental model against the data that AppLand captures. It's not uncommon to find unexpected behavior where you least expect it.

Sharing your findings

Now pass along what you've learned to your colleagues or include it in a bug report. Snapshots of unexpected or erroneous behavior contain a wealth of information useful in diagnosing, triaging, reproducing, and fixing application defects.

Your recording can be always be viewed by anybody within your organization. To make sure that anyone with the link can view the page, enable link sharing. To do this, click the edit icon at the top right of the page. Check the box to enable link sharing. Users who have the page URL will now always be able to view your recording (even without logging in).