AppMap sharing

AppMaps are great for sharing your knowledge about how old and new code works and behaves. This guide describes suggested workflows for sharing AppMaps with your peers.

How AppMap sharing works

AppMaps are json files that can be viewed by anyone with an AppMap interactive viewer. The viewer is available in:

  • The AppMap extension for VSCode and JetBrains code editors. The viewer is seamlessly integrated in the IDEs, with direct links to source files in your project. The extension visualizes AppMap files stored locally on your filesystem.
  • AppMap Cloud. This SaaS application visualizes AppMaps in supported web browsers, and provides links to sources files stored in private or public GitHub or GitLab repostitories. AppMap Cloud visualizes AppMaps stored in its repository.

AppMap sharing strategies

Here are a few suggested strategies for sharing your AppMap files with your peers:

  1. Upload AppMap files to AppMap Cloud, an online AppMap repository and interactive viewer.
  2. Attach AppMap files to your online resources, such as bug tickets, Wiki pages, Pull & Merge Requests, Slack channels and other resources that allow for the exchange or attachment of files.
  3. Copy AppMap files to file sharing services or shared network drives.

Sharing AppMaps with AppMap Cloud

AppMap Cloud is a fast and convenient method for sharing AppMaps:

  • It’s optimized for storing, sharing and visualizing AppMap files.
  • AppMap files can be uploaded to AppMap Cloud in seconds from code editors or with the AppMap browser extension in only a few clicks. AppMap files can also be uploaded with scripts from your CI/CD pipeline.
  • AppMaps uploaded to AppMap Cloud can be viewed by opening a link in a web browser. The flow is similar to sharing Google Maps: Simply navigate to a code object of interest in the AppMap, copy the sharing link and send the link to your peers.

Uploading to AppMap Cloud from code editors

Upload AppMaps to AppMap Cloud without leaving your code editor:

  1. Open an AppMap in your code editor.
  2. Click on the “upload to cloud” icon in the top right corner of the AppMap diagram.
  3. A new web browser window will open with the AppMap now in AppMap Cloud. If you aren’t already signed in, you may be asked to sign in/sign up with your GitHub or GitLab account.
  4. Click on the “Share AppMap” icon in AppMap Cloud and copy the shareable link.
  5. Share the link with your peers. For example, you can add it to a bug ticket in GitHub, Jira or other issue tracking application.

Upload and link AppMap to a GitHub issue

Viewing AppMaps shared in AppMap Cloud

When someone shares an AppMap published in AppMap Cloud, you’ll receive a link and have two options for using the AppMap:

  1. You can work with the AppMap in the AppMap Cloud interactive viewer in a web browser, or
  2. You can open the AppMap in the Cloud, then download it to your disk and open it in AppMap for JetBrains or VSCode.

Download from AppMap Cloud gif

Recording and sharing AppMaps with the browser extension

AppMaps can be recorded from AppMap-instrumented web applications and uploaded to AppMap Cloud with the AppMap browser extension directly from your web browser.

Advanced sharing strategies

Uploading and sharing of AppMaps can be automated and integrated into your development workflows. AppMap recording and uploading scripts can be added to your CI/CD pipeline so you have AppMaps available for every published release or for each major code update. To learn more, visit CLI for AppMap Cloud.

Attaching AppMaps to code tickets

A simple way of adding an AppMap to an issue is to insert the AppMap JSON file as an attachment. You can reveal the location of the AppMap file using the AppMap extension for your code editor.

Warning: Files with a JSON extension cannot be directly attached to GitHub issues. We recommend that you zip .appmap.json files prior to attaching them.

In code editors:

  1. Right click on the AppMap editor window tab and pick “Reveal in Finder/Explorer” (VSCode) or “Open in Finder/Explorer” (JetBrains).
  2. A Finder/Explorer window will open with the AppMap file selected.
  3. Right click on the file and compress/zip it.
  4. Attach the zip file to the code issue.

Attach AppMap to a GitHub issue

Downloading and viewing attached AppMaps

AppMaps attached to tickets can be directly saved as .appmap.json files into project folders and opened in code editors. You’ll need AppMap for JetBrains or VSCode installed in order to open downloaded AppMaps.

  1. In the ticket page, locate the attachment.
  2. Save the attachment to your project folders. If it’s a zip file, right click and unzip it. If it has any other extension, save it as a .appmap.json file. Files with a different extension or with just a .json extension will not be recognized or opened in the interactive viewer.
  3. Open the downloaded file in your code editor.

Download as an attachment gif

AppMaps and file sharing services

If your organization uses file sharing services or shared network drives, these are excellent methods for sharing AppMap appmap.json files with your team:

  1. Record AppMaps in your project folders.
  2. Copy the recorded AppMaps from your project folders to the shared folders. You can see the location of the AppMap files on disk in your code editor:
    • Right click on the AppMap editor window tab and pick “Reveal in Finder/Explorer” (VSCode) or “Open in Finder/Explorer” (JetBrains).
    • A Finder/Explorer window will open with the AppMap file selected.

Note: You can add the shared folders to your VSCode Workspace for quick copying of AppMaps between folders right in your code editor:

  • From the File menu, pick the Add Folder to Workspace... menu and select a shared folder.

Viewing AppMaps in shared folders

To view AppMaps (.appmap.json files), you’ll need a supported code editor (VSCode or a JetBrains IDE) and the AppMap extension.

Simply open any appmap.json file in your filesystem with your code editor and the AppMap will open with the AppMap interactive viewer.


Was this page helpful? thumb_up Yes thumb_down No
Thank you for your feedback!