“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.“1
However, like all forms of documentation, a sequence diagram is only useful when it is current and accurate. 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. The sequence diagram format is described in the UML standard.
You can use AppMap to view and interact with sequence diagrams of your application right in your code editor. AppMap can also generate sequence diagrams comparisons to make it easy to see the differences in runtime behavior caused by a coding change.
Sequence diagrams can be also exported as SVG images, or in popular text formats like PlantUML so that you can edit and share the diagrams however you prefer. AppMap sequence diagrams can also be generated on the command line, making it simple to use within a CI build to generate up-to-date sequence diagrams every time a change is made on your primary development branches.
The AppMap extensions for Visual Studio Code and JetBrains include support for viewing AppMaps as sequence diagrams. Simply open any AppMap and click on the Sequence Diagram
tab to view it in the main editor window.
Sequence Diagrams follow these conventions:
Scrolling down within a sequence diagram in the editor retains the lifeline labels at the top, making it easy to keep track of which vertical line belongs to which entity. You can select function calls to see their details, or to see the same event in Trace View for even more detail.
By default, AppMap Sequence Diagrams will contain “lifelines” for each of the actors in your application. If you would prefer not to see any of those, just click on the “X” within the lifeline label to remove it. This can be useful when hiding less important calls such as those to made a central logging package.
Lifelines that have been hidden can be re-shown using the “Filters” control, or by resetting the map using the “Clear” control.
Function calls that contain other events can be collapsed to make the diagram easier to read. This is done using the [-]
control.
Clicking on the [+]
control will expand the same sequence set once again.
Sequence diagrams can be exported from the code editor as SVG image files. Any lifelines that are hidden from view will also not appear in the exported image.
To export a sequence diagram, click on EXPORT
and the SVG data will appear in a new file in your project. Save that file to a desired location and then open it with a web browser or other suitable tool to view it.
Some of the advanced features below require installation of the PlantUML library.
Download the PlantUML JAR file from https://plantuml.com/download
Configure the file location:
AppMaps can be generated on the command line from your terminal, or within a CI build.
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
When two AppMaps are similar, it can be useful to represent them as sequence diagrams and then compare them. This is most useful:
Sequence diagram comparisons can be attached to GitHub Pull Requests to make it easier for reviewers to better understand changes in code.
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
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:
sequence-diagram
command with the option --format plantuml
<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.
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
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"]