@appland/appmap 3.146.0 → 3.147.0

package/built/docs/setup-appmap-in-ci/matrix-builds.md

@@ -0,0 +1,225 @@
+---
+layout: docs
+title: Set up AppMap in CI
+description: "Optimize GitHub Actions for matrix builds to deploy AppMap efficiently. Modify actions, add triggers, analyze results, and streamline installation configurations."
+name: Matrix Builds with GitHub Actions
+setup-appmap-ci: true
+step: 5
+render_with_liquid: false
+---
+
+## Matrix Builds with GitHub Actions
+
+- [Step 1: Modify Action to Support Matrix Build](#step-1-modify-action-to-support-matrix-build)
+- [Step 2: Add the Build Triggers and Analysis Step](#step-2-add-the-build-triggers-and-analysis-step)
+- [(Optional) Step 3: Remove Installation Actions and Configuration](#optional-step-3-remove-installation-actions-and-configuration)
+- [Step 4: Merge this PR to deploy AppMap](#step-4-merge-this-pr-to-deploy-appmap)
+
+
+If your project uses matrix builds in order to split your test runs across multiple runners, you will need some additional configuration for AppMap to properly save and merge AppMaps from across all these runs. 
+
+From the [GitHub documents](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs) on the `matrix strategies`:
+
+> A matrix strategy lets you use variables in a single job definition to automatically create multiple job runs that are based on the combinations of the variables. For example, you can use a matrix strategy to test your code in multiple versions of a language or on multiple operating systems.
+> Use `jobs.<job_id>.strategy.matrix` to define a matrix of different job configurations. Within your matrix, define one or more variables followed by an array of values.
+
+For example, to split tests across two runners you could set a matrix strategy like the following:
+
+```yaml
+strategy:
+  fail-fast: false
+  matrix:
+    ci_node_total: [2]
+    ci_node_index: [0, 1]
+```
+{: .example-code}
+
+For AppMap to analyze any failed test cases, you need to include the configuration flag `fail-fast: false` in your matrix strategy. 
+
+### Step 1: Modify Action to Support Matrix Build
+
+When following the Getting Started Guide In [Step 1](/docs/setup-appmap-in-ci/in-github-actions.html#step-1-create-an-initial-baseline-appmap-inventory-report), you'll need to make a few changes and additions to your GitHub Workflow file before you commit the first step.
+
+First, modify the `EndBug/add-and-commit` action to include an if statement so that only one of the runners will commit the AppMap library installation files to the project. 
+
+For Example:
+```yaml
+- name: Commit changes
+  if: ${{ matrix.ci_node_index == 0}} #Only run this action on a single runner
+  uses: EndBug/add-and-commit@v9
+```
+{: .example-code}
+
+Next, you'll modify the `archive-action` to configure an `archive-id:` set to the unique index of the runner. This will archive each tarball of AppMaps from each runner in your Action.
+
+For example:
+```yaml
+- name: Archive AppMaps
+  if: always()
+  uses: getappmap/archive-action@v1
+  with:
+    archive-id: ${{ matrix.ci_node_index }} # Set this equal to the unique index of the runner
+```
+{: .example-code}
+
+After the action which runs your test cases, you will create a new job that will merge the AppMaps from your individual runners, archive them, and provide the initial AppMap inventory report.
+
+Create a new job at the same level as the job which runs the test cases, and make this job dependant on the previous job.
+
+For example:
+```yaml
+merge-and-archive:
+  runs-on: ubuntu-latest
+  if: always()
+  needs: [test]
+
+  steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+      with:
+        ref: ${{ github.event.pull_request.head.ref }}
+
+    - name: Install AppMap tools
+      uses: getappmap/install-action@v1
+      with:
+        install-appmap-library: false
+
+    - name: Merge AppMaps
+      uses: getappmap/archive-action/merge@v1
+      with:
+        revision: ${{ github.event.pull_request.base.sha }}
+        archive-count: 2 # Set this equal to the total number of test runners (i.e. total archives created)
+```
+{: .example-code}
+
+Commit the changes:
+
+```bash
+$ git add .
+$ git commit -m "ci: Bootstrap initial AppMap archive"
+```
+{: .example-code}
+
+View an example workflow [file for this step here](https://github.com/land-of-apps/sample_rails_matrix_build/blob/5825614c9c7530c2108b14b030be1efcd2d40fec/.github/workflows/appmap-analysis.yml).
+
+Push the changes upstream to your branch and open a new Pull Request which will trigger the GitHub action. Once the build of this PR completes, AppMap will comment on the PR with an initial report about your software project.
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/action-welcome-to-appmap.webp"/> 
+
+The initial AppMap report will give you details about:
+
+- **Runtime Analysis:** Analyzing the AppMap data for security flaws and anti-patterns  
+- **REST API analysis** For AppMaps that include HTTP server requests, AppMap can automatically generate OpenAPI definitions.
+- **SQL Profile**  When your code makes a SQL query, AppMap records the SQL query in detail. It even parses the queries
+to figure out which tables your app is using, and how it's using them.
+
+### Step 2: Add the Build Triggers and Analysis Step
+
+With the previous step complete, and a inventory report in your pull request, you can now replace the `merge-and-archive` job we used in the last step and replace it with the `appmap-analysis-matrix` reusable workflow with an additional configuration option `archive-count`.
+
+The `archive-count` is the total number of test runners which have generated AppMap archives. For example, if you have split your test runner across 2 hosts, you need to set the `archive-count` equal to `2`.
+
+For example:
+```yaml
+appmap-analysis:
+  if: always()
+  needs: [test]
+  uses: getappmap/analyze-action/.github/workflows/appmap-analysis-matrix.yml@v1
+  with:
+    archive-count: 2 # Set to the total number of test runners
+  permissions:
+    actions: read
+    contents: read
+    checks: write
+    pull-requests: write
+```
+{: .example-code}
+
+Pull the latest commit made by the previous GitHub Action workflow run
+
+```bash
+$ git pull
+```
+{: .example-code}
+
+Commit the changes:
+
+```bash
+$ git add .
+$ git commit -m "ci: Add build triggers and analysis step"
+```
+{: .example-code}
+
+Push the changes upstream to your branch.
+```bash
+$ git push
+```
+{: .example-code}
+
+After the build completes, AppMap will post details of the Analysis build into your pull request. 
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/action-report-summary.webp"/> 
+
+View an example workflow [file for this step here](https://github.com/land-of-apps/sample_rails_matrix_build/blob/03d10c03430c84b05542eeca9408c46297dfd97c/.github/workflows/appmap-analysis.yml).
+
+If your pull request report shows changes to code behavior or new AppMaps (when no changes are made), you may have some non-deterministic tests. For additional help resolving this, please contact the AppMap engineering team via [email](mailto:support@appmap.io) or join the [AppMap Community Slack](https://appmap.io/slack).
+
+### (Optional) Step 3: Remove Installation Actions and Configuration
+
+Now that AppMap configuration files are included in your project, you no longer need the `permissions` block at the top of your action (unless required for other actions) and `add-and-commit` actions in your project. Additionally, modify the `install-action` to disable library installation. The Action will require the AppMap CLI tools installed to successfully archive the AppMaps from each runner. If they are left in place your project will always update to the latest released versions of AppMap libraries. Remove the following lines to have more control over future software updates.
+
+This action can be deleted.
+
+```yaml
+- name: Commit changes
+  if: ${{ matrix.ci_node_index == 0}}
+  uses: EndBug/add-and-commit@v9  
+```
+{: .example-code}
+
+Unless needed for other Actions in your workflow, modify this section with updated permissions from Step 1:
+
+```yaml
+permissions:
+  contents: write
+```
+{: .example-code}
+
+
+Modify the `install-action` with the following setting:
+
+```yaml
+- name: Install AppMap tools
+  uses: getappmap/install-action@v1
+  with:
+    install-appmap-library: false
+```
+{: .example-code}
+
+Finally, you can set your `checkout` action back to the default.
+```yaml
+- name: Checkout
+  uses: actions/checkout@v3
+```
+{: .example-code}
+
+After removing those Actions, add and commit to your branch.
+
+```bash
+$ git add .
+$ git commit -m "ci: Remove installation actions"
+```
+{: .example-code}
+
+Push the changes upstream to your branch.
+```bash
+$ git push
+```
+{: .example-code}
+
+<p class="alert alert-info">
+See an example GitHub Action configuration with AppMap working with a <a href="https://github.com/land-of-apps/sample_rails_matrix_build/blob/appmap/.github/workflows/appmap-analysis.yml" target="_blank">multi-runner matrix build</a>.
+</p>
+
+### Step 4: Merge this PR to deploy AppMap
+Congratulations! You’ve successfully set up the AppMap Github Action and can now merge this into your project to make it available for every other developer to use on each of their subsequent pull requests. 

package/built/docs/setup-appmap-in-ci/troubleshooting.md

@@ -0,0 +1,71 @@
+---
+layout: docs
+title: Set up AppMap in CI
+description: "Learn how to troubleshoot common issues when integrating AppMap into your GitHub Actions."
+name: Troubleshooting
+setup-appmap-ci: true
+step: 6
+---
+
+# Troubleshooting AppMap in GitHub Actions <!-- omit in toc -->
+
+- [The AppMap GitHub Action Does Not Run in my Environment](#the-appmap-github-action-does-not-run-in-my-environment)
+- [I Can't Open AppMaps in my Pull Request Report](#i-cant-open-appmaps-in-my-pull-request-report)
+
+## The AppMap GitHub Action Does Not Run in my Environment
+
+**Add AppMap to GitHub Allowed Actions**
+
+If your organization limits which GitHub Actions can be used, [update your organization settings](https://docs.github.com/en/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#allowing-select-actions-and-reusable-workflows-to-run) to allow the specific AppMap actions required for this integration to work. All AppMap Actions are published on the [GitHub Marketplace](https://github.com/marketplace?type=actions&query=getappmap+) under the `getappmap` owner namespace.
+
+In the top right corner of GitHub.com, click your profile photo, then click **Your organizations**.
+
+<img class="video-screenshot" src="/assets/img/docs/github-your-organizations.webp"/> 
+
+Next to the organization, click **Settings**.
+
+In the left sidebar, click **Actions**, then click **General**.
+
+Under "Policies", select **Allow _OWNER_, and select _non-OWNER_, actions and reusable workflows** and add the following AppMap required actions. This will ensure that current and future actions will be supported. 
+
+```
+getappmap/*
+```
+
+Alternatively, if you would like to restrict to only the current list of actions further you can list them individually. You will need to keep this list updated as new features and functionality are added. 
+```
+getappmap/install-action@*,getappmap/archive-action@*,getappmap/analyze-action@*
+```
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/action-permissions.webp"/> 
+
+## I Can't Open AppMaps in my Pull Request Report
+
+This is caused by not having the AppMap GitHub App installed in your GitHub account.
+
+**Install or Request the AppMap GitHub App**
+
+The **AppMap** application authorizes your account to run AppMap in CI. It also enables you to open AppMaps in your browser.
+
+The **AppMap** application:
+
+- **DOES NOT** transfer any of your repository code, data, or AppMaps to an external server.  
+- **DOES** confirm that you have access via GitHub permissions to the AppMap data stored in your repository action.  
+- **DOES** open a browser tab with a signed URL that enables your browser to securely download the AppMap data from your GitHub and display it.  
+- **DOES** directly transfer data from YOUR GitHub to YOUR browser, **without** going through any other other 3rd party services.  
+
+Organization owners can install GitHub Apps on their organization. If you are not an organization owner, you can still initiate the install process. GitHub will then send a notification to the organization owner to request them to approve the installation. Ask your organization owner to approve that request.
+
+If you're installing into your personal account, you will already have permissions to install this app there.
+
+1) Open the [AppMap GitHub marketplace page](https://github.com/marketplace/get-appmap) and click `Set up a plan`.
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/marketplace-page.webp"/>
+
+2) Select the GitHub account in which you are using AppMap, and then click the `Install` button.
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/account-selection.webp"/>
+
+3) Select `All Repositories`, or select to install the app into specific repositories.
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/select-repos.webp"/> 

package/built/docs/setup-appmap-in-your-code-editor/add-appmap-to-your-code-editor.md

@@ -0,0 +1,93 @@
+---
+layout: docs
+setup-appmap-ide: true
+title: Docs - AppMap in your Code Editor
+description: "Integrate AppMap into your Code Editor easily with AppMap for Visual Studio Code and JetBrains IDEs."
+step: 2
+name: Add AppMap to your Code Editor
+redirect_from: [/docs/add-appmap-to-a-project/, /docs/install-appmap-agent, /docs/quickstart, /docs/quickstart/index.html]
+---
+
+# Add AppMap to your Code Editor
+
+- [AppMap for Visual Studio Code](#appmap-for-visual-studio-code)
+  - [Activate AppMap in Visual Studio Code](#activate-appmap-in-visual-studio-code)
+- [AppMap for JetBrains IDEs](#appmap-for-jetbrains-ides)
+  - [Activate AppMap in JetBrains IDEs](#activate-appmap-in-jetbrains-ides)
+- [Keep your extension up to date](#keep-your-extension-up-to-date)
+  - [Update AppMap for Visual Studio Code](#update-appmap-for-visual-studio-code)
+  - [Update AppMap for JetBrains code editors](#update-appmap-for-jetbrains-code-editors)
+  
+## AppMap for Visual Studio Code
+
+The AppMap extension is listed on the <a href="https://marketplace.visualstudio.com/items?itemName=appland.appmap" target="_blank">Visual Studio Code Marketplace</a>.
+
+<img title="AppMap available in Visual Studio Code" class="inline-partial-screenshot" src="/assets/img/docs/vscode-marketplace-tab-in-IDE.png">
+
+1. Open extensions from the sidebar in Visual Studio Code
+2. Type 'AppMap' into the search bar
+3. Click to install
+
+<a class="btn btn-dark btn-with-inline-img" href="https://marketplace.visualstudio.com/items?itemName=appland.appmap">
+    <img class="inline-button-img" src="/assets/img/vscode-icon.svg">
+    Install from the VS Code Marketplace
+</a>
+
+### Activate AppMap in Visual Studio Code
+
+After installing and opening the extension, you will need to first activate AppMap with your email address or with your GitHub or GitLab account.  Activating AppMap only generates a valid license key associated with your account and does NOT send any of your source code or sensitive data to AppMap systems.  For more information refer to the [AppMap Security FAQ](/security).
+
+<div class="alert alert-info">If you do not see an option to <b>Activate AppMap</b>, upgrade to the <a href="https://marketplace.visualstudio.com/items?itemName=appland.appmap">latest version </a>of the AppMap extension.</div>
+
+<img title="Activate AppMap in VS Code" class="inline-partial-screenshot" src="/assets/img/docs/activate-vscode.webp">
+
+## AppMap for JetBrains IDEs
+
+The AppMap plugin has official support for **IntelliJ**, **PyCharm**, and **RubyMine** listed on the <a href="https://plugins.jetbrains.com/plugin/16701-appmap" target="_blank">JetBrains Marketplace</a>.
+
+<img title="AppMap available in JetBrains IDE" class="inline-partial-screenshot" src="/assets/img/docs/jetbrains-marketplace-tab-in-IDE.webp">
+
+1. Start your JetBrains IDE and open Preferences
+2. Open Plugins, then click on Marketplace
+3. Search for AppMap, select and install AppMap
+
+<a class="btn btn-dark btn-with-inline-img" href="https://plugins.jetbrains.com/plugin/16701-appmap">
+    <img class="inline-button-img" src="/assets/img/jetbrains.svg">
+     Install from the JetBrains Marketplace
+</a>
+
+### Activate AppMap in JetBrains IDEs
+
+After installing and opening the extension, you will need to first activate AppMap with your email address or with your GitHub or GitLab account.  Activating AppMap only generates a valid license key associated with your account and does NOT send any of your source code or sensitive data to AppMap systems.  For more information refer to the [AppMap Security FAQ](/security).
+
+<div class="alert alert-info">If you do not see an option to <b>Activate AppMap</b>, upgrade to the <a href="https://plugins.jetbrains.com/plugin/16701-appmap">latest version</a> of the AppMap plugin.</div>
+
+<img title="AppMap available in JetBrains IDE" class="inline-partial-screenshot" src="/assets/img/docs/activate-jetbrains.webp">
+
+## Keep your extension up to date
+
+New development happens fast at AppMap. Keep your extension up to date to take advantage of new features.
+
+### Update AppMap for Visual Studio Code 
+
+<p class="alert alert-info">To get access to <a href="https://appmap.io/product/appmap-navie">AppMap Navie</a> you need to be running AppMap VS Code Plugin version >= 0.118.1</p>
+
+To update AppMap for Visual Studio Code navigate to the extensions tab > installed. Select 'AppMap' from your installed extensions and click the update button.
+
+Alternatively you can update to the latest AppMap software release on the [the VS Code Marketplace.](https://marketplace.visualstudio.com/items?itemName=appland.appmap) 
+
+<image class="video-screenshot" src="/assets/img/docs/update-appmap-for-visual-studio-code.webp"/> 
+
+**NOTE**: Make sure to either reload the extension, or reload/restart VS Code after updating the plugin.
+
+### Update AppMap for JetBrains code editors
+
+<p class="alert alert-info">To get access to <a href="https://appmap.io/product/appmap-navie">AppMap Navie</a> you need to be running AppMap JetBrains Plugin version >= 0.64.0</p>
+
+To update AppMap for JetBrains code editor open the Settings window and select Plugins. Select 'AppMap' from your installed extensions and click the update button.
+
+Alternatively you can update to the latest AppMap software release on the [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/16701-appmap)
+
+<image class="video-screenshot" src="/assets/img/docs/update-appmap-for-intellij.webp"/> 
+
+**NOTE**: Make sure to either reload the extension, or reload/restart JetBrains after updating the plugin.

package/built/docs/setup-appmap-in-your-code-editor/appmap-analysis.md

@@ -0,0 +1,77 @@
+---
+layout: docs
+title: Docs - AppMap in your Code Editor
+description: "AppMap Runtime Analysis scans AppMap Data to detect code flaws, presenting findings in your editor for preemptive fixes."
+name: AppMap Analysis
+setup-appmap-ide: true
+step: 8
+redirect_from: [/docs/your-first-15-minutes-with-appmap/appmap-analysis,/docs/analysis/in-your-code-editor,/docs/analysis/]
+---
+
+# AppMap Analysis
+
+When there is AppMap Data available in your project, AppMap Runtime Analysis will immediately scan them to detect flaws in the code. These flaws are surfaced as **findings** and are displayed in your code editor as you work so that they can be addressed **before** they are propagated to test or production environments.
+
+## Navigate findings
+
+AppMap makes information about findings available in two main locations:
+
+- [The **Runtime Analysis** step of the setup instructions](#the-runtime-analysis-step-of-the-setup-instructions)
+- [The **Runtime Analysis** sidebar pane](#the-runtime-analysis-sidebar-pane)
+
+### The **Runtime Analysis** step of the setup instructions
+
+#### Visual Studio Code
+<image class="video-screenshot" src="/assets/img/docs/last-step-of-setup-instructions.webp"/> 
+
+#### JetBrains editors
+<image class="video-screenshot" src="/assets/img/docs/last-step-of-setup-instructions-jetbrains.webp"/> 
+
+### The **Runtime Analysis** sidebar pane
+
+In Visual Studio Code, findings are displayed In the Runtime Analysis sidebar pane sorted by impact category and type.
+
+<image class="video-screenshot" src="/assets/img/docs/runtime-analysis-sidebar-findings.webp"/> 
+
+Clicking the ‘Overview’ link in the Runtime Analysis sidebar will open the ‘Runtime Analysis Summary’ window which contains a summary of findings for a particular project.
+
+<image class="video-screenshot" src="/assets/img/docs/runtime-analysis-overview-dashboard.webp"/> 
+
+{% include vimeo.html id='916087872' %}
+
+---
+
+**In this video**  
+AppMap Analysis scans your AppMap Data to find software design flaws that impact performance, stability, security and maintainability. This runtime code analysis can find the problems that static code analyzers miss - and that cause 90% of today’s most serious production issues.
+
+**Links mentioned**  
+[AppMap Community Slack](/slack)  
+[Get AppMap for VSCode](https://marketplace.visualstudio.com/items?itemName=appland.appmap)  
+[Get AppMap for JetBrains](https://plugins.jetbrains.com/plugin/16701-appmap)
+
+---
+
+## Follow along
+
+AppMap Analysis is available for both JetBrains IDEs and Visual Studio Code. 
+
+## Investigate findings
+
+Let's look at a sample Ruby on rails application, where AppMap has already been installed and AppMap Data has been generated. From the test cases, you'll see a new option for findings in the left-hand column or an option here for investigate findings.
+
+<img class="video-screenshot" src="/assets/img/appmap-analysis-1.webp"/>
+
+You can see one of the issues we've found is that a log event contained secret data by clicking on the finding will be taken directly to the line of code where this event occurs by hovering over the pin.
+<img class="video-screenshot" src="/assets/img/appmap-analysis-2.webp"/>
+
+## Use labels to visually explore your code
+
+You can open the AppMap and see exactly where the function wrote this secret to a log file. How does AppMap know that this was a secret? Unlike static analyzers and other tools that do pattern matching AppMap knows this function generates secrets because we have built in knowledge of common software libraries with pre-populated labels.
+
+We know exactly where to look to avoid false positives. Developers can extend their labels, whether it's a common library or not with simple code comments on their functions.
+<img class="video-screenshot" src="/assets/img/appmap-analysis-3.webp"/>
+
+If you search for the secret label, you'll see the location in the code where this event occurs by clicking on the function, you'll be taken to the exact location of the AppMap, where the secret was generated. Additionally, you can open the code, combining a visual model alongside the code.
+<img class="video-screenshot" src="/assets/img/appmap-analysis-4.webp"/>
+
+**Next step: [Join the AppMap Community](/community)**

package/built/docs/setup-appmap-in-your-code-editor/generate-appmap-data-from-tests.md

@@ -0,0 +1,93 @@
+---
+layout: docs
+title: Docs - AppMap in your Code Editor
+description: "Automatically generate AppMap Data from test cases using AppMap, benefiting from named cases, source locations, and incremental testing for various frameworks."
+name: Generate AppMap Data from Tests
+setup-appmap-ide: true
+step: 3
+redirect_from: [/docs/recording-methods,/docs/your-first-15-minutes-with-appmap/generate-appmaps-with-tests, /docs/quickstart/intellij/step-3, /docs/quickstart/pycharm/step-3, /docs/quickstart/vscode/javascript-step-3.html, /docs/quickstart/rubymine/step-3, /docs/quickstart/vscode/python-step-3, /docs/quickstart/vscode/ruby-step-3, /docs/quickstart/vscode/java-step-3, ./reference/remote-recording.html, /docs/quickstart/vscode/step-2, /docs/diagrams/quickstart/vscode/ruby-step-3-tests, /docs/quickstart/vscode/java-step-3.html, /docs/quickstart/vscode/python-step-3.html, /docs/quickstart/vscode/ruby-step-3.html, /docs/quickstart/webstorm/step-3, /docs/diagrams/quickstart/vscode/java-step-3-tests, /docs/diagrams/quickstart/vscode/javascript-step-3-tests, /docs/diagrams/quickstart/vscode/python-step-3-tests, /docs/diagrams/quickstart/vscode/ruby-step-3-tests, /docs/diagrams/quickstart/intellij/step-3-tests, /docs/diagrams/quickstart/webstorm/step-3-tests, /docs/diagrams/quickstart/pycharm/step-3-tests, /docs/diagrams/quickstart/rubymine/step-3-tests, /docs/setup-appmap-in-your-code-editor/generate-appmaps-from-tests]
+---
+
+# Generate AppMap Data from Tests
+
+AppMap integrates with popular test frameworks, so you can automatically record an AppMap from each test case that you run.
+
+Some benefits of test case recording include:
+
+* **Named for the test case** The name of each AppMap corresponds to the name of the test.
+* **Includes source location** The AppMap metadata contains the path and line number of the test case. From the AppMap Diagram, you can navigate to the test case code.
+* **Supports incremental testing** AppMap's dependency analysis capability can help you re-run out-of-date test cases as you modify the code - even in very large repositories.
+
+For details on test case recording, see:
+
+- [Tests recording - Ruby](/docs/reference/appmap-ruby#tests-recording)
+- [Tests recording - Python](/docs/reference/appmap-python#tests-recording)
+- [Tests recording - Java](/docs/reference/appmap-java#tests-recording)
+- [Tests recording - Node.js](/docs/reference/appmap-node#tests-recording)
+
+{% include vimeo.html id='916087911' %}
+
+---
+
+**In this video**  
+We install AppMap into our sample Ruby on Rails project inside of VS Code. You can find a link to the sample project below if you would like to follow along.
+
+**Links mentioned**  
+[Rails Sample Application](https://github.com/land-of-apps/sample_app_6th_ed/tree/codespaces-devcontainer)  
+[AppMap Slack community](/slack)
+
+---
+
+## Follow along
+
+You can review the previous video for more details about what the [ideal types of projects for AppMap](/docs/your-first-15-minutes-with-appmap/ideal-projects) are. We're using a Ruby on Rails sample app and can use `bundle exec rails test` to generate AppMap Data from test cases. This is how AppMap will analyze the runtime of the code.
+
+## Install AppMap agent
+
+**NOTE:** If you're using JetBrains IntelliJ IDEA with Java, [follow these instructions](/docs/reference/jetbrains#start-with-appmap-for-java) to create AppMap Data from tests.
+
+From here, navigate to AppMap by clicking on the button in the left hand sidebar, and click on "Add AppMap to your project". The project picker will help you confirm that you're running a suitable project before you install.
+
+The automated installer will look for project files such as a `Gemfile` or a `package.json` and it will ask you to confirm the details of your environment before installing. 
+
+Choose an installation method to continue.
+
+In the video example the automated installer identifies both `yarn` and `Bundler` because the project consists of a Ruby on Rails application with additional frontend JavaScript dependencies. In this case we want to record our Rails server, so `Bundler` is selected as our installation target.
+
+Once the agent is installed correctly, continue on to the next step, recording AppMap Data.
+
+<img class="video-screenshot" src="/assets/img/appmap-install.webp"/>
+
+## Recording AppMap Data
+
+Follow the on-screen instructions for recording AppMap Data for your project. You'll receive one of the two following options.
+
+You may be given a command to copy and paste which will guide you through running your test cases with AppMap enabled. Paste the command into a terminal and it will ask what you want to use for your test command. It will make an assumption based on your project. If the command you run tests with is different to what was suggested by the on-screen instructions, you can change this command by pressing no, then entering a new command and include any environment variables you need.
+
+Confirm the test command and define the maximum time you want to spend running each test. Tests will run for 30 seconds in total by default before AppMap will stop recording. If your tests take longer than 30 seconds, specify a larger time period.
+
+Alternatively, the instructions may prompt you to run your application or test cases as normal. In this scenario, AppMap will automatically be enabled and no additional steps are necessary.
+
+<img class="video-screenshot" src="/assets/img/appmap-record.webp"/>
+
+## Open AppMap Diagrams
+
+By running this command we've generated 68 AppMap Diagrams in our Rails sample project, and we can continue on to the next step. We now have AppMap Data that has been generated. We surface some of the AppMap Diagrams here, maybe ones that have a large number of requests or in this scenario, ones that have large numbers of SQL queries. You can click on any one of these to open the map directly inside of your vs code. You'll be able to see which tests executed and generated this AppMap. You will also be able able to see server requests, packages, classes, functions, and SQL queries related to this.
+
+<img class="video-screenshot" src="/assets/img/generate-appmaps-5.webp"/>
+
+## Investigate findings and view code objects
+
+We'll continue on the onboarding process and be able to view any findings that the analysis function has picked out. When we click on the "View Problems" button, we'll see a series of N-plus-one SQL queries. These could lead to performance issues for your users. By clicking on any of these findings, it will navigate us into the code base where this issue is occurring.
+
+You can also see code objects have been indexed. This is another helpful way to be able to find which AppMap Diagrams include which specific SQL queries or specific API requests. From here, you can see the changes that we've made in our project to support creating AppMap Data. The `appmap.yml` file includes the command that we're going to execute as part of our test run, as well as which paths within our project we're going to analyze.
+
+And you can also see the `Gemfile`. We include AppMap as a development dependency. You can commit all of these files, which will make this available to any other developers on this project.
+
+Finally, you'll see AppMap Data actually exists inside your temp directory in the AppMap folder. We don't recommend committing these to your project. They can grow your git repositories unnecessarily.
+
+If you'd like to learn more about how to share AppMap Diagrams with your team, reach out to us on [Slack](/slack) for a preview of at maps team offerings.
+
+AppMap is now installed in our project and by running tests locally with the AppMap flag enabled, we will be able to record AppMap Diagrams.
+
+<img class="video-screenshot" src="/assets/img/generate-appmaps-7.webp"/>