@appland/appmap 3.146.0 → 3.147.0

package/built/docs/reference/uninstalling-appmap.md

@@ -0,0 +1,119 @@
+---
+layout: docs
+title: Docs - Reference
+description: "Learn how to uninstall AppMap components like IDE plugins, libraries, and generated files from your project to clean up after usage effectively."
+toc: true
+reference: true
+name: Uninstalling AppMap
+step: 19
+---
+
+# Uninstalling AppMap
+AppMap consists of several components, each of which may require a different uninstall approach depending on what changes were made to your applications during installation.
+
+- [Uninstalling AppMap](#uninstalling-appmap)
+  - [Uninstalling AppMap IDE Plugins](#uninstalling-appmap-ide-plugins)
+    - [Uninstalling the AppMap VS Code Extension](#uninstalling-the-appmap-vs-code-extension)
+    - [Uninstalling the AppMap JetBrains Plugin](#uninstalling-the-appmap-jetbrains-plugin)
+  - [Removing AppMap libraries from your application](#removing-appmap-libraries-from-your-application)
+    - [Ruby](#ruby)
+    - [Java](#java)
+    - [Python](#python)
+  - [Removing AppMap-generated files from your project](#removing-appmap-generated-files-from-your-project)
+
+## Uninstalling AppMap IDE Plugins
+
+### Uninstalling the AppMap VS Code Extension
+To uninstall AppMap from VS Code, first select the Extensions control to view your installed extensions. 
+<img class="video-screenshot" src="/assets/img/docs/extensions-vsc.png"/>
+
+Next, find and select `AppMap` in the list of installed extensions. Then click the `Uninstall` button to remove the AppMap extension from your editor.
+<img class="video-screenshot" src="/assets/img/docs/uninstall-vsc.png"/>
+
+Finally, if your project supports AppMap [Launch Configurations](https://appmap.io/docs/reference/vscode.html#run-with-appmap-for-java), you can now remove the AppMap specific details in the `.vscode/launch.json` and the `.vscode/settings.json` files. 
+
+<img class="video-screenshot" src="/assets/img/docs/launch-configuration-uninstall.webp"/>
+
+<p class="alert alert-info">
+Please note that even after uninstalling the IDE extension, your project may still be configured to load an AppMap library and continue to record maps when your application is run. You should follow the language-specific uninstall instructions below to remove the AppMap library from your project.
+</p>
+
+### Uninstalling the AppMap JetBrains Plugin
+To uninstall AppMap from JetBrains editors like IntelliJ and PyCharm, open your editor's `Settings` panel from the main menu. Select `Plugins` on the left panel, then find and select `AppMap` in the list of installed plugins. Then click the `Uninstall` button to remove the AppMap extension from your editor.
+<p>
+<img class="video-screenshot" src="/assets/img/docs/plugins-jetbrains.webp"/>
+</p>
+
+<p class="alert alert-info">
+Please note that even after uninstalling the IDE plugin, your project may still be configured to load an AppMap library and continue to record maps when your application is run. You should follow the language-specific uninstall instructions below to remove the AppMap library from your project.
+</p>
+
+## Removing AppMap libraries from your application
+Removing AppMap from your application typically involves removing the AppMap library from your project's dependencies. Language-specific instructions on how to do this are below.
+
+### Ruby
+Use the `bundle` command to remove the AppMap library from your project:
+
+{: .example-code}
+
+```console
+$ bundle remove appmap
+```
+
+Or you can remove the appmap gem globally if installed at the system level. 
+
+{: .example-code}
+
+```console
+$ gem uninstall appmap
+```
+
+Alternatively, manually remove the line containing `appmap` from the top of your Gemfile. 
+
+### Java
+For IntelliJ users, the act of uninstalling the AppMap plugin from the IDE is enough to fully remove AppMap configuration from your project. 
+
+VS Code users should remove the AppMap launch commands from the files `launch.json` and `settings.json`, both located in the `.vscode` folder.
+
+If you had also installed the [AppMap Maven plugin](https://appmap.io/docs/reference/appmap-maven-plugin.html), you should remove the appropriate AppMap `<plugin>` definition from your `pom.xml`. Similarly, if you had installed the [AppMap Gradle plugin](https://appmap.io/docs/reference/appmap-gradle-plugin.html#installation), you should remove the AppMap `plugins` section from your `build.gradle` or `build.gradle.kts` file.
+
+### Python
+Remove AppMap using your Python dependency manager:
+
+{: .example-code}
+
+```console
+Using pip:
+$ pip uninstall appmap
+
+Using poetry:
+$ poetry remove appmap
+
+Using pipenv:
+$ pipenv uninstall appmap
+```
+
+Also, if your project contains a `requirements.txt` file, you should remove `appmap` from that file too.
+
+### Node.js
+Your Node project dependencies were not modified to use AppMap. Simply changing your application's launch command
+to no longer prepend `npx appmap-node` is enough to stop using AppMap.
+
+## Removing AppMap-generated files from your project
+If you had generated AppMap Data, you will have a number of files in your project folder that can safely be removed after completing the uninstall steps above. This is an optional step.
+
+Start by removing the AppMap configuration file:
+
+{: .example-code}
+
+```console
+$ rm appmap.yml
+```
+
+Finally, remove any generated AppMap files from your project:
+
+{: .example-code}
+
+```console
+$ rm -r tmp/appmap
+```

package/built/docs/reference/vscode.md

@@ -0,0 +1,122 @@
+---
+layout: docs
+title: Docs - Reference
+description: "Explore AppMap features in Visual Studio Code: AppMap panel, runtime analysis, code objects, Java integration, extension actions, remote recording, OpenAPI generation."
+toc: true
+reference: true
+name: AppMap for Visual Studio Code
+step: 1
+---
+
+# AppMap for Visual Studio Code
+
+- [AppMap panel](#appmap-panel)
+  - [Instructions](#instructions)
+  - [AppMap Diagram tree view](#appmap-diagram-tree-view)
+  - [Runtime Analysis](#runtime-analysis)
+  - [Code Objects](#code-objects)
+- ["Run with AppMap" for Java](#run-with-appmap-for-java)
+- [Extension actions](#extension-actions)
+- [Remote recording](#remote-recording)
+- [Generate OpenAPI Definitions](#generate-openapi-definitions)
+- [GitHub repository](#github-repository)
+
+## AppMap panel
+
+### Instructions
+
+Step-by-step instructions for configuring a project to use AppMap and using the main features.
+
+Once you've configured AppMap for a project, commit the file changes to Git so that your colleagues don't have to do the setup themselves.
+
+### AppMap Diagram tree view
+
+The AppMap view shows all AppMap Diagrams in your open projects. You can open it from the top level menu (View -> Open view... -> AppMap), with an AppMap action or by clicking on its icon in the side bar.
+
+AppMap Diagrams are organized by how they were created (request recording, remote recording, test case recording).
+
+Within the AppMap tree view you can
+
+* Click on any AppMap name to open the diagram
+* Right-click for a context menu
+
+You can also use the tree view buttons to Filter the AppMap tree by name, or search for a specific AppMap. There are also extension commands to do this.
+
+### Runtime Analysis
+
+AppMap can find automatically find software design flaws that impact security, performance, stability, and maintainability. When a problem is found, it's listed here. Click on the problem to get detailed information about it.
+
+### Code Objects
+
+All the HTTP server requests, SQL queries, packages, classes, and functions that are present in an AppMap are listed here in a tree view. You can navigate through these code objects to see what's present in your project. Click on any code object to open the AppMap Diagram that contains it.
+
+## "Run with AppMap" for Java
+
+**NOTE:** This section only applies to Java applications.
+
+Installing the AppMap VC Code plugin adds a default [Launch Configuration](https://code.visualstudio.com/docs/editor/debugging) which supports the integrated VS Code debugger. These can be used to run your Java application code with AppMap automatically configured, saving you from manually changing your Maven or Gradle settings. This is the recommended approach for all Java users using the VS Code editor.
+
+To run your tests with AppMap enabled, navigate to the `Testing` section of VS Code in the left hand menu icons. If your project has tests you will see them listed in the following screen. From here, click on the `Run Tests` icon, highlighted in the screenshot below. This will kick off your test cases with the AppMap libraries installed and enabled. 
+
+<img class="video-screenshot" src="/assets/img/vscode-run-with-tests.webp"/> 
+
+To run your application with AppMap enabled, navigate to the `Run and Debug` section of VS Code in the left hand menu icons. You will see a new launch configuration in the in the drop down which says `Run with AppMap` alongside any other launch configurations for your project.  With the `Run with AppMap` launch configuration select click on the "Play" icon, highlighted in the screenshot below. This will start your application with the AppMap libraries installed and enabled.  You can now interact with your application to generate [request recordings](/docs/reference/appmap-java.html#requests-recording) or use [remote recording](#remote-recording).
+
+<img class="video-screenshot" src="/assets/img/vscode-run-with-appmap.webp"/> 
+
+After installing the VS Code AppMap extension for your Java project, you will notice a new launch configuration in the `.vscode` directory in your project. 
+
+<img class="video-screenshot" src="/assets/img/docs/vscode-launch-configuration.webp"/> 
+
+Next, click on the "Run and Debug" menu option in the left hand column of VS Code
+
+<img class="video-screenshot" src="/assets/img/docs/vscode-run-and-debug.png"/> 
+
+Clicking on the "Play" button next to the "Run with AppMap" launch configuration will start your Java application with the necessary AppMap configuration flags enabled by default. 
+
+When your application is running you can proceed to record AppMap Data using either [Requests Recording](/docs/reference/appmap-java#requests-recording) or [Remote Recording](https://appmap.io/docs/reference/vscode.html#remote-recording)
+
+
+## Extension actions
+
+To open the list of AppMap extension actions, press `CTRL+SHIFT+P` or `COMMAND+SHIFT+P` on macOS and type `AppMap`. 
+
+Most of the command names should be self-explanatory. Here are a few commands which are a bit more complicated:
+
+- **AppMap: Filter/Find AppMap by name** Opens the AppMap side bar view and the filter/find text field
+- **AppMap: Login**, **AppMap: Logout** Some extension functionality requires you to login to the AppMap Server. You'll be prompted to do this when you setup AppMap for the first time. You can also login and logout using the built-in `Accounts` feature of VSCode.
+- **AppMap: Touch Out-of-Date Test Files** If you have AppMap Diagrams generated from test cases, this command will determine which tests need to be re-run in order to bring the AppMap Data up-to-date. It will then "touch" (update the modified date) of each out-of-date test case. You can use a file watching trigger program like `Guard` (Ruby), `grunt` or `gulp` (JS) to re-run the test cases as they are touched.
+- **AppMap: Copy Out-of-Date Tests to Clipboard** Similar to the "Touch Out-of-Date Test Files" command, but places the file names on the clipboard
+- **AppMap: Open Code Object in AppMap** Using this command you can find and open AppMap Diagrams for any code object (package, class, function, route, etc) in your project.
+
+## Remote recording
+
+You can make a [remote recording](../recording-methods#remote-recording) from within the VSCode IDE. First, start your application with remote recording enabled. Exactly how to do this depends the language you're using - consult the [agent reference](/docs/reference) for details.
+
+To start a recording, click the remote recording button, or use the command **AppMap: Start a Remote Recording**.
+
+![Start remote recording](/assets/img/docs/vscode-remote-start.png)
+
+Interact with your app through its UI or API. Then use the stop remote recording button again, or use the command **AppMap: Stop the Remote Recording**. 
+
+![Stop remote recording](/assets/img/docs/vscode-remote-stop.png)
+
+You'll be prompted to save the AppMap to a file, and it will be opened.
+
+![Prompt remote recording](/assets/img/docs/vscode-remote-save.png)
+
+For more details about remote recording, see:
+
+* [Recording methods > Remote recording](../recording-methods#remote-recording)
+* [Remote recording API](../reference/remote-recording-api)
+
+## Generate OpenAPI Definitions
+
+After [recording AppMap Data](/docs/recording-methods.html) for your project, open the command pallette using `CTRL+SHIFT+P` or `COMMAND+SHIFT+P` on macOS, type `AppMap: Generate OpenAPI`, then hit `Enter`. This will open a new file with your OpenAPI definition document. Save this file locally, share with your team, or ingest as a [new collection into API tools like Postman.](https://blog.postman.com/new-postman-integration-with-appmap-create-and-manage-always-accurate-collections/)
+
+![alt_text](/assets/img/openapi/openapi-1.webp "OpenAPI export to file")
+
+
+## GitHub repository
+
+[https://github.com/getappmap/vscode-appland](https://github.com/getappmap/vscode-appland)

package/built/docs/setup-appmap-in-ci/example-projects.md

@@ -0,0 +1,21 @@
+---
+layout: docs
+title: Set up AppMap in CI
+description: "Explore workflow examples for AppMap GitHub Action in various languages & frameworks like Ruby on Rails, Java Spring, Python Django, and Node.js."
+name: Example Projects
+setup-appmap-ci: true
+step: 4
+redirect_from: [/docs/setup-appmap-in-ci/in-github-actions.html#workflow-examples]
+---
+
+## Workflow examples
+
+Reference implementations of the AppMap GitHub Action are available for the following languages and frameworks:
+
+* [**Ruby on Rails**](https://github.com/land-of-apps/sample_rails_app/blob/appmap/.github/workflows/appmap-analysis.yml)
+* [**Ruby on Rails w/ Matrix Build**](https://github.com/land-of-apps/sample_rails_matrix_build/blob/appmap/.github/workflows/appmap-analysis.yml)
+* [**Java Spring**](https://github.com/land-of-apps/sample_spring_app/blob/appmap/.github/workflows/appmap-analysis.yml)
+* [**Java Spring w/ multiple sub-projects**](https://github.com/land-of-apps/waltz/blob/appmap-analysis/.github/workflows/appmap-analysis.yml)
+* [**Python Django**](https://github.com/land-of-apps/django-oscar/blob/appmap/.github/workflows/appmap-analysis.yml)
+* [**Python w/ Matrix Build**](https://github.com/land-of-apps/sample_django_app/blob/appmap/.github/workflows/appmap-analysis.yml)
+* **Node.js** Coming soon!

package/built/docs/setup-appmap-in-ci/how-it-works.md

@@ -0,0 +1,43 @@
+---
+layout: docs
+setup-appmap-ci: true
+title: Set up AppMap in CI
+description: "Optimize CI with AppMap Analysis, tracking behavioral changes in each Pull Request. Get started by installing the AppMap GitHub App from the GitHub Marketplace."
+step: 1
+name: How it works
+redirect_from: [/docs/analysis/in-ci]
+---
+# Set Up AppMap in CI
+
+AppMap Analysis can work with your Continuous Integration (CI) system to collect, store, analyze, and report on the behavioral changes within each Pull Request. 
+AppMap will analyze the changes in your application on each pushed commit or pull request. AppMap performs a thorough analysis of the runtime differences, giving you:
+
+* Root cause analysis of failed tests.  
+* Web service API changes - breaking and non-breaking - via comparison of generated OpenAPI definitions.  
+* New and resolved security findings.  
+* New and resolved performance findings.  
+* New and resolved findings in other categories - maintainability, reliability, and user-defined rules.  
+* “Behavioral diffs” as sequence diagrams showing changed runtime behavior within the PR.  
+
+<p class="alert alert-info">
+Install the <a href="https://github.com/marketplace/get-appmap" target="_blank">AppMap GitHub App</a> on the GitHub Marketplace to get started now!
+</p>
+
+The AppMap Analysis GitHub actions can run cooperatively or independently of your existing CI job. 
+For example, AppMap Analysis can run as a GitHub Action even if you do not use GitHub Actions as your CI system.
+
+AppMap Analysis runs entirely within your existing GitHub account and does not send code or data to an external or 3rd-party server. For more information, refer to the [AppMap Security FAQ](https://appmap.io/security).
+
+Once you create a pull request, AppMap data is recorded as your test cases run. As AppMaps are generated, an AppMap archive file is created that includes all the AppMap data, plus some metadata about the job. As code is pushed to a branch, AppMap Analysis create an archive file for that code revision. This archive file is automatically saved as a CI artifact.  Once an archive has been created, it can be compared to the “base” revision (i.e. your mainline or production branch).  
+1
+## The value of AppMap in CI
+
+We designed AppMap’s findings as a comment in the PR itself to enable the Development, QA, Architecture, and Security teams to review code faster, evaluate code independently, and catch deep-rooted code issues easier. This helps you determine the stability of new code in the context of where the code actually lives and allows for faster and more reliable code delivery. 
+
+By simply browsing the PR comments, a DevOps team can reliably deploy code with the assurance that it meets all needed code quality requirements, reducing the amount of unnecessary communication between teams just to get the code live long before it is ever pushed to production.
+
+## Requirements
+If you have already generated AppMaps outside of CI (for example, by running your test cases locally), you can quickly deploy AppMap in CI using the same commands used to execute your test cases. If you already have an existing CI job that builds an environment to execute your test cases, AppMap Analysis can be added to that job.
+
+## Next steps
+- [Add to GitHub Actions](/docs/analysis/in-github-actions)