How to use AppMap Diagrams

The AppMap extension for your editor automatically displays AppMap files as beautiful diagrams you can interact with.

• Interact with the Dependency Map
• Using the Sequence Diagram view
• Working with the Trace diagram

Select an item of interest in the left-hand navigation bar

Use the navigation bar for quick navigation to items of interest, for example, HTTP routes, labels, packages, classes, functions.

View and interact with the Dependency Map

The Dependency Map diagram shows all the code that’s relevant to what you’re working on and how it’s connected. Here you can search and navigate through web services, code, libraries, dependency services, and SQL, all in the context of a specific feature.

The dependency map is fully interactive. You can:

• Expand and collapse packages and Web Service endpoints
• View detailed information about dependencies and classes
• List the functions of a class that are used by the executed code
• Explore callers and callees
• View SQL queries. See SQL tips and tricks in the next section.
• Open source code right to the line of any particular function.

Using the Sequence Diagram view

The Sequence Diagram view shows an application’s behavior in a linear chronological layout. Function calls are shown as horizontal arrows, ordered from top to bottom as they occurred at runtime. The elements in the sequence diagram are interactive and can be selected, collapsed, and hidden.

Sequence diagrams can also be exported as SVG files for easy sharing and collaboration. Similar AppMaps can also be compared in a sequence diagram “diff” to reveal changes in runtime behavior caused by a code update.

For more information, see the Sequence Diagram reference.

View and interact with the Trace diagram

The Trace diagram shows all the details of how a feature works. Here you can navigate forward, backward, up, and down through a detailed execution trace. See the call tree starting with web service endpoints going through function calls all the way to SQL operations. At any point, you can move quickly back and forth between the Trace view and your source code.

The Trace is fully interactive. You can:

• Expand and collapse execution paths
• Explore callers and callees
• View variable names and values at any point in the code flow
• View SQL queries
• Open source code right to the line of any particular function

Demo of using AppMaps

This video demonstrates how to use AppMap Diagrams when learning how unfamiliar code works:

How to read SQL code in AppMaps

The AppMap extension for your editor displays SQL commands in AppMap Diagrams so you can understand how your application logic interacts with the database. You can quickly discover SQL inefficiencies and anti-patterns that pose hidden scalability and reliability risks even if your application seems to be working well.

With the AppMap extension, not only are trips to database logs no longer required to see the SQL commands, but the SQL commands are also directly linked to the code that initiates their execution, helping developers understand the direct impacts of their code updates on database operations and performance.

View all SQL commands, pick a command of interest, and drill down to details

When you open an AppMap, the navigation bar lists all captured SQL commands. This is a great starting point for your SQL investigation:

• Browse the list of SQL commands, pick a command, and click on it to drill down to details
• View the SQL command in the Trace to see how it is connected to upstream/downstream code and other SQL commands
• Click on the Caller link to see the function call that initiated the command’s execution.

Search for specific SQL commands/tables/columns

Use the search box in the Navigation bar to select for a specific subset of SQL Commands:

• Search for a specific SQL command such as SELECT, UPDATE, INSERT, etc.
• Search for a table or column name
• Use regular expressions for complex searches, filtering the results by multiple criteria, for example, SELECT.*_orders.*

View SQL commands executed by a specific class or package

When you click on a dependency link in the Dependency Map, the navigation bar will list events specific to that relationship.

• Select a link between the database icon and a class to see SQL commands executed by functions of that class
• Click on a SQL command to drill down to details.

Spot complex SQL patterns

When investigating how efficiently the application code or the ORM utilizes the database, it’s helpful to see whether multiple SQL commands are clustered together and whether they form any specific (anti-)patterns. The Trace view is a great visual tool for spotting clusters and repetitions of SQL commands enveloped by code that are difficult to discover using database logs or other simple tools.

• In the AppMap, switch to the Trace view
• Start with any of the SQL commands in the navigation bar and investigate how they are connected with other SQL commands or code blocks
• When looking for N+1-like patterns, look for repetitive SQL SELECTs fetching single records using a specific ID
• Use the zoom controls, arrow keys, panning, and expand/collapse functions to navigate around the trace efficiently.

Example: How to spot and fix Django ORM anti-patterns

In this video example, you can learn how to optimize Django ORM by seeing how it makes SQL queries under the hood. The video explains the role of ORM in modern applications, SQL efficiency challenges, and how to use AppMap for uncovering and fixing the infamous N+1 anti-pattern

---