Using AppLand to visually auto-document a software application

AppLand enables teams to automatically and visually document the architecture and behavior of production releases and under-development features and software code written in Java and Ruby. AppLand’s real-time, interactive depictions of software behavior can be used by teams to augment their documentation, such as READMEs, and to contextualize software behavior by allowing the “code to speak for itself." Think of these diagrams as a UI for your software backend systems.

This tutorial uses the open-source application Discourse, written in Ruby, as an example project. You can add this application to your environment from the public open-source library of apps in AppLand. Other sample applications available in AppLand include CyberArk Conjur, Jenkins, and the Spring Pet Clinic.

You can record and upload test cases of your own applications using the AppLand client tools.

You will be brought to the All applications view. Here you will find a list of all the applications in your organization available for you to view.

Clicking on the name of the application you want to learn about brings you to the summary view of your application.

The Application profile page provides high-level information about your application’s key components by displaying its key architectural elements, data, and service structure.

At the top of the Application profile page is the Mapset selector. A mapset is a set of AppMaps which were all recorded together from the same version of the application code.

Each mapset has properties which you can use to decide which one you want to see. For example, the environment property indicates whether the mapset was built on a developer's local machine or in an official CI/CD environment. The version property indicates the application version, if the code is from a specific version. The branch and commit properties tell you exactly which source code was mapped.

In this example, see 2,460 AppMaps for Discourse generated on host hachiko.local.

Mapsets whose environment property is ci indicates that the mapset was built and uploaded by an official CI/CD system such as Jenkins or Travis. ci mapsets will always indicate the branch name and commit number of the code. Mapsets from ci are authoritative for that branch and version, since they come from an official build environment.

The highlight of the Application profile page is the Component diagram. The Component diagram is a "boxes-and-lines" diagram of the key web services, packages, classes, and databases which are used by the application. Initially, a component diagram of the entire app is displayed.

You can customize the Component diagram using the filter controls. Filters allow you to focus the Component diagram on a specific subset of the AppMaps in the mapset. For example, choosing a Feature filter redraws only the components that participate in the selected feature. Here, the Component diagram is displaying just the components that are used to create a new invite.

Below the Component diagram is Related AppMaps. Any time you're looking at the Component diagram, the Related AppMaps table shows the AppMaps that are used to compute the diagram. You can further focus the AppMap table by entering a keyword in the search box. Here are the AppMaps which are related to the component diagram displayed above.

The Web service view lists all the known web service resources in the application, along with all the known routes are available for these resources. Within a route, you can open all the AppMaps that make a request to that route. This view can be used to complement hand-written REST API documentation. If a web service is present in the documentation but not in the AppLand Web services view, then it may not have any test cases. If a web service is present in the Web services view but not in the documentation, then the doc team either doesn’t know about the service or hasn’t gotten to it yet.

In the list below, notice that posts has 22 routes while some services only have 1 or 2. This is a strong indicator that posts is a key service.

When teams are documenting software for certification or review, there are often key areas of interest that reviewers would like to focus on. For example, special attention may be paid to code changes which impact sensitive data flows, security, resilience, and scalability. AppLand records “AppMaps” from running code and test cases. An AppMap is an atomic visualization of part of the code as it executes. An AppMap is typically scoped to a single test case in a CI/CD environment, or a single user interaction in the case of a browser trace (more on that later in the Debugging tutorial). Careful inspection of AppMaps is an ideal way to inspect and review the behavior of application functionality, without having to setup and run the application code directly.

First, find an AppMap associated with one of the core functions of the application that you are interested in reviewing. Then use the AppLand AppMap view to see how the code actually executes and follow along with the code.

In the case of Discourse, we know that posts represent a key web service because Discourse is an app for online discussions. We can assume that requests to GET /posts/:id will give us a representative flow of retrieving a post, and illustrate all the checks, calls, and business logic associated with this type of activity. So, starting at the Application profile view for Discourse, filter the Component diagram to show PostsController #create, then choose an AppMap such as "PostsController #show succeeds".

This is the AppLand visualization of that AppMap:

The AppMap view consists of a sequence-style diagram illustrating key function calls and I/O performed during this test case. The bottom of the view provides a timeline display of the code execution path.

You can use the arrow buttons to navigate back and forth along the control flow. In stepping through this AppMap you can see, in detail, the series of checks that a post request is subjected to.

The flow view and timeline will navigate synchronously through the execution flow, so you can see where you are in either trace.

Here we see one point where a post request performs a permission check, to ensure that the user is allowed to see the post.

Here we see, in detail, how user authentication tokens are looked up to login a user for the current request. We can report on this key functionality for the project due to the fact that it is used for a core component of the security of the system.

To quickly open a GitHub page with source code for a selected call, right-click on the call and select the View source option.

We can understand the data I/O associated with this particular feature by limiting the view to just the SQL functions. This is an excellent way to document specific changes to data associated with this feature. Choose the filter icon under the flow graph.

These are the available filters you can use to limit what is returned in the AppMap flow view.

By excluding function name matches, you will return only the SQL queries and the parent functions of those queries in the flow diagram.