Sequence Diagrams

“A sequence diagram shows process interactions arranged in time sequence in the field of software engineering. It depicts the processes involved and the sequence of messages exchanged between the processes needed to carry out the functionality.“¹

However, like all forms of documentation, a sequence diagram is only useful when it’s current and accurate. So AppMap gives you the ability to instantly generate sequence diagrams of any recorded program. A generated sequence diagram is accurate and easy to produce, and it can be re-created on demand.

You can use AppMap to generate and compare sequence diagrams from your code editor, or you can use the CLI tools. Sequence diagrams can be generated as SVG images, or in popular text formats like PlantUML so that you can edit and share the diagrams however you prefer.

Generating sequence diagrams from a single map

Any AppMap can be exported as a sequence diagram. By default, the entire AppMap is represented in the diagram. The following conventions apply:

1. Inbound HTTP server requests (if any) will be on the left hand side
2. Database queries and RPC requests (e.g. HTTP client requests) (if any) will be on the right hand side.
3. Each code package is represented as a sequence diagram “actor” - each actor is a vertical lane which you can follow down the page.
4. Each function call is represented as a line from one actor to another.
5. The function return value (if any) will be depicted in the opposite direction.
6. If an AppMap contains HTTP server requests, other “root” events which are not HTTP server requests will be filtered out, by default.
7. When you generate the diagram, you can choose to hide any packages that you feel are not pertinent to understanding the code flow.
8. You can also choose to expand any package or packages into its member classes. However, there’s a risk that this may cause the diagram to consume too much horizontal space and become unreadable.

Code editor extensions

VSCode

Download the PlantUML JAR file from https://plantuml.com/download

Configure the file location:

Right-click on an AppMap, or run the command AppMap: Generate Sequence Diagram

Sequence Diagram support is not yet available in JetBrains IDEs. You can use the AppMap CLI to generate sequence diagrams - see the next section for details.

CLI command: sequence-diagram

You can generate sequence diagrams using the AppMap CLI command sequence-diagram.

An example:

$ npx @appland/appmap@latest sequence-diagram --format plantuml tmp/appmap/minitest/Following_followers_page.appmap.json

Comparing sequence diagrams

When two AppMaps are similar, it can be useful to represent them as sequence diagrams and then compare them. This is most useful:

1. To compare AppMaps of two different test cases, requests, or remote recordings.
2. To compare two different versions of the same AppMap - before and after a code change.

Sequence diagram comparisons can be attached to GitHub Pull Requests to make it easier for reviewers to better understand changes in code.

Code editor extensions

VSCode

CLI command: sequence-diagram-diff

For example, compare two similarly named AppMaps:

$ npx @appland/appmap@latest sequence-diagram-diff --format plantuml  Following_followers_page.appmap.json Followers_following_page.appmap.json

For example, compare two versions of the same AppMap:

$ npx @appland/appmap@latest sequence-diagram-diff --format plantuml  tmp/v1/Following_followers_page.appmap.json tmp/v2/Following_followers_page.appmap.json

Integrating with other tools

e.g. tools that accept Mermaid or PlantUML syntax

AppMap can generate sequence diagrams in the PlantUML format, a textual format which is portable and easy to modify. So you can touch up the generated diagrams, and copy-paste the diagram text into a wide variety of tools that support the PlantUML format, such as Atlassian Confluence.

There are two ways to generate a PlantUML sequence diagram:

1. Run the sequence-diagram command with the option --format plantuml
2. Generate a sequence diagram from the code editor. Then locate the sequence diagram file in the file tree, and you’ll see a <name>.sequence.uml file.

You can copy the file contents directly into other tools, or you can customize it first like. If you are going to edit the PlantUML file, be sure and save it as a new file first.

CLI Reference

sequence-diagram

npx @appland/appmap@latest sequence-diagram appmap

Generate a sequence diagram for an AppMap

Positionals:
  appmap                                                     [string] [required]

Options:
      --version     Show version number                                [boolean]
  -v, --verbose     Run with verbose logging                           [boolean]
      --help        Show help                                          [boolean]
  -d, --directory   program working directory                           [string]
      --output-dir  directory in which to save the sequence diagrams
      --format      output format
                             [choices: "plantuml", "json"] [default: "plantuml"]
      --exclude     code objects to exclude from the diagram

sequence-diagram-diff

npx @appland/appmap@latest sequence-diagram-diff base-diagram head-diagram

Diff sequence diagrams that are represented as JSON

Positionals:
  base-diagram  base diagram file or directory to compare             [required]
  head-diagram  head diagram file or directory to compare             [required]

Options:
      --version     Show version number                                [boolean]
  -v, --verbose     Run with verbose logging                           [boolean]
      --help        Show help                                          [boolean]
  -d, --directory   program working directory                           [string]
      --output-dir  directory in which to save the sequence diagrams
                                                                  [default: "."]
      --format      output format
                             [choices: "plantuml", "json"] [default: "plantuml"]

Notes