@appland/appmap 3.146.0 → 3.147.0

package/built/docs/reference/index.md

@@ -0,0 +1,25 @@
+---
+layout: docs
+title: Docs - Reference
+description: "Explore a range of AppMap tools and agents for various languages like Ruby, Python, Java, and more, along with CLI, API, and GitHub Action integration."
+toc: true
+step: 1
+redirect_from: [/docs/reference/browser-extension]
+---
+
+# Reference
+- [AppMap for Visual Studio Code](/docs/reference/vscode)
+- [AppMap for JetBrains](/docs/reference/jetbrains)
+- [AppMap Navie AI](/docs/reference/navie)
+- [AppMap Agent for Ruby](/docs/reference/appmap-ruby)
+- [AppMap Agent for Python](/docs/reference/appmap-python)
+- [AppMap Agent for Node.js](/docs/reference/appmap-node)
+- [AppMap Agent for Java](/docs/reference/appmap-java)
+    - [AppMap for Java – Maven Plugin](/docs/reference/appmap-maven-plugin)
+    - [AppMap for Java – Gradle Plugin](/docs/reference/appmap-gradle-plugin)
+- [AppMap Command line interface (CLI)](/docs/reference/appmap-client-cli.html)
+- [Remote recording API](/docs/reference/remote-recording-api)
+- [Analysis Rules](/docs/reference/analysis-rules)
+- [Analysis Labels](/docs/reference/analysis-labels)
+- [GitHub Action](/docs/reference/github-action)
+- [Uninstalling AppMap](/docs/reference/uninstalling-appmap)

package/built/docs/reference/jetbrains.md

@@ -0,0 +1,136 @@
+---
+layout: docs
+title: Docs - Reference
+description: "AppMap for JetBrains reference guide. Learn to use AppMap in your JetBrains code editor."
+toc: true
+reference: true
+name: AppMap for JetBrains
+step: 2
+---
+
+# AppMap for JetBrains
+
+- [AppMap tool window](#appmap-tool-window)
+- ["Start with AppMap" for Java](#start-with-appmap-for-java)
+  - [Create AppMap Data from JUnit test runs](#create-appmap-data-from-junit-test-runs)
+    - [Disable specific JUnit tests](#disable-specific-junit-tests)
+  - [Running a Java application with AppMap](#running-a-java-application-with-appmap)
+- [Remote recording](#remote-recording)
+- [AppMap Plugin actions](#appmap-plugin-actions)
+- [Generate OpenAPI Definitions](#generate-openapi-definitions)
+- [Troubleshooting](#troubleshooting)
+  - [Enable Debug Logging](#enable-debug-logging)
+  - [Downloading Plugin Logs](#downloading-plugin-logs)
+- [GitHub Repository](#github-repository)
+
+## AppMap tool window
+
+The AppMap tool window shows all AppMap Diagrams in your open projects. You can open it from the top level menu (`View -> Tools Windows -> AppMaps`), with an AppMap action or by clicking on its tab in the UI.
+
+<img class="intellij-screenshot" src="/assets/img/intellij-appmap-tool-window.webp"/>
+
+AppMap tool window actions:
+
+- Alphabetical listing of all AppMap Diagrams in the project, sorted by name.
+- Double-click on any AppMap to open it.
+- Search for an AppMap by its name.
+- Start/stop [remote recordings](#remote-recording).
+- View the Quickstart guide.
+
+## "Start with AppMap" for Java
+
+**NOTE:** This section only applies to Java applications.
+
+Installing the AppMap JetBrains plugin adds custom buttons and menu options to the JetBrains editor interface. 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 JetBrains editors like IntelliJ.
+
+For example, if you right click on your main class file you'll see a new menu item under "More Run/Debug" to `Start with AppMap`. Selecting this option will start your application with the AppMap libraries enabled.  From here, you can interact with your application to generate [request recordings](/docs/reference/appmap-java.html#requests-recording) or use [remote recording](#remote-recording)
+
+<img class="intellij-screenshot" src="/assets/img/jetbrains-run-main-with-appmap.webp"/>
+
+You can also use this custom button to run a specific test or group of tests with the `Start with AppMap` option. Similar to above, right click on a single test or a group of tests and use the custom button under "More Run/Debug" to `Start with AppMap`.
+
+<img class="intellij-screenshot" src="/assets/img/jetbrains-run-test-with-appmap.webp"/>
+
+{% include vimeo.html id='916087828' %}
+
+### Create AppMap Data from JUnit test runs
+
+1. [Install the JetBrains plugin](https://plugins.jetbrains.com/plugin/16701-appmap) if you haven't already.
+2. Open your test file in the editor. Each method marked with JUnit's `@Test` annotation will produce an AppMap.
+3. Run the test(s) with AppMap by clicking the icon next to the test class and then selecting "Start with AppMap", or by clicking the AppMap run configuration button:
+<img class="intellij-screenshot" src="/assets/img/run-config-test.png"/>
+
+#### Disable specific JUnit tests
+
+To disable recording for a particular JUnit test (for example, a performance
+test), list the class or methods under `exclude` in the project's `appmap.yml` configuration file.
+
+### Running a Java application with AppMap
+
+When you run a Java application with the AppMap agent, [remote recording](/docs/recording-methods.html#remote-recording) will be enabled. (Note: For this to work, your application must include a web server).
+
+1. [Install the JetBrains plugin](https://plugins.jetbrains.com/plugin/16701-appmap) if you haven't already.
+2. Open your application file in the editor.
+3. Run your application with AppMap by clicking the icon next to the main class you wish to run and then selecting "Start with AppMap", or by clicking the AppMap run configuration button:
+<img class="intellij-screenshot" src="/assets/img/run-config-start.png"/>
+1. With the application running, follow the [remote recording](#remote-recording) instructions below to (starting at step 3) create AppMap Data.
+
+## Remote recording
+
+You can make a [remote recording](../recording-methods#remote-recording) from within the JetBrains IDE. 
+
+1. [Install the JetBrains plugin](https://plugins.jetbrains.com/plugin/16701-appmap) if you haven't already.
+2. Start your application with remote recording enabled. For Java, [run your Java application with AppMap](#running-a-java-application-with-appmap). For other languages, consult the [agent reference](/docs/reference) for details.
+3. To start a recording, click the remote recording button, or use the command **Start AppMap recording**. 
+<img class="intellij-screenshot" src="/assets/img/docs/intellij-remote-start.png"/>
+4. Enter the URL where your application is running.
+<img class="intellij-screenshot" src="/assets/img/docs/intellij-remote-url.png"/>
+5. Interact with your app through its UI or API. Then click the button to stop the recording, or use the command **Stop AppMap recording**. 
+<img class="intellij-screenshot" src="/assets/img/docs/intellij-remote-stop.png"/>
+6. You'll be prompted to save the AppMap to a file, and it will be opened.
+<img class="intellij-screenshot" src="/assets/img/docs/intellij-remote-save.png"/>
+
+For more details about remote recording, see:
+
+* [Recording methods > Remote recording](/docs/recording-methods)
+* [Remote recording API](../reference/remote-recording-api)
+
+## AppMap Plugin actions
+
+To open the list of AppMap plugin actions, press `CTRL+SHIFT+A` on Windows and Linux, or `COMMAND+SHIFT+A` on macOS, and type `AppMap`. You can also find these actions at `Tools > AppMap` of the main menu.
+
+The command names should be self-explanatory. 
+
+## Generate OpenAPI Definitions
+
+After [recording AppMap Data](/docs/recording-methods.html) for your project, select "Generate OpenAPI" from the AppMap instructions quick start in the lower right hand column. 
+
+![Generate OpenAPI Link](/assets/img/openapi/jetbrains-1.webp)
+
+Selecting the "Generate OpenAPI Definitions" button will open a new file with your OpenAPI definition document to save locally, share with your team or use with 3rd party API management tools [like Postman](https://blog.postman.com/new-postman-integration-with-appmap-create-and-manage-always-accurate-collections/)
+
+![OpenAPI Generation Screen](/assets/img/openapi/jetbrains-2.webp)  
+
+## Troubleshooting
+
+### Enable Debug Logging
+
+You can enable debug logging of the AppMap plugin in your JetBrains code editor by first opening `Help` > `Diagnostic Tools` > `Debug Log Settings`. 
+
+![JetBrains Debug Log menu](/assets/img/jetbrains-debug-logs.webp)  
+
+In the `Custom Debug Log Configuration` enter `appland` to enable DEBUG level logging for the AppMap plugin. 
+
+![JetBrains Debug Log Configuration](/assets/img/jetbrains-logging-configuration.webp)  
+
+Next, open `Help` > `Show Log...` will open the IDE log file. 
+
+![JetBrains Debug Show Log](/assets/img/jetbrains-show-log.webp)
+
+### Downloading Plugin Logs
+
+AppMap technical support may ask you for your IDE logs to diagnose issues with the plugin's behavior. If so, go to the `Help` menu in your editor and select `Collect Logs and Diagnostic Data`. This will create a `.zip` file on your local machine and open a file explorer window to it. You can then safely send that file to AppMap within your technical support ticket conversation.
+
+## GitHub Repository
+
+[https://github.com/getappmap/appmap-intellij-plugin](https://github.com/getappmap/appmap-intellij-plugin)

package/built/docs/reference/license-key-install.md

@@ -0,0 +1,74 @@
+---
+layout: docs
+title: Docs - Reference
+description: "Install your AppMap license key for VS Code and JetBrains by following these steps."
+toc: true
+reference: true
+step: 18
+name: License Key Installation
+---
+
+# AppMap Code Editor license key installation
+
+After receiving your AppMap license key follow the steps below. 
+
+For the license key to successfully validate with AppMap systems ensure your machine is able to connect to <a href="https://getappmap.com">https://getappmap.com</a>. You can test by opening it in your web browser.
+
+- [VS Code license key install steps](#vs-code-license-key-install-steps)
+- [JetBrains license key install steps](#jetbrains-license-key-install-steps)
+
+## VS Code license key install steps
+
+1) Open the VS Code Command Palette
+   - Mac: `Cmd + Shift + P`
+   - Windows/Linux: `Ctrl + Shift + P`
+
+2) Search for `AppMap license`
+
+<img class="video-screenshot" src="/assets/img/license-key-vscode-1.webp"/> 
+
+3) Enter the license key provided by the AppMap team and press `Enter` to submit
+
+<img class="video-screenshot" src="/assets/img/license-key-vscode-2.webp"/> 
+
+4) Click `Allow` to allow the AppMap extension to use your license key.
+
+<img class="video-screenshot" src="/assets/img/license-key-vscode-3.webp"/> 
+
+5) AppMap will be activated for Visual Studio Code.
+
+<br/>
+
+## JetBrains license key install steps
+
+1) Select `Tools` from the main menu of your JetBrains Code Editor. Then select `AppMap` -> `Enter License Key`.
+
+<img class="video-screenshot" src="/assets/img/license-key-jetbrains-1.webp"/> 
+
+2) Enter the license key provided by the AppMap team and press `Ok` to submit.
+
+<img class="video-screenshot" src="/assets/img/license-key-jetbrains-2.webp"/> 
+
+3) You will now be logged into AppMap for the IDE.
+
+<img class="video-screenshot" src="/assets/img/license-key-jetbrains-3.webp"/> 
+
+### Video: How to Install an AppMap license key in JetBrains
+
+<div class="video-container" onclick="JetBrainsplayVideo()">
+  <img id="JetBrainsvideoPlaceholder" src="/assets/img/appmap-license-jetbrains-placeholder.webp" style="display:block; width: 100%;">
+  <video id="JetBrainsvideoPlayer" playsinline loop style="display:none;">
+    <source src="/assets/video/appmap-license-key-jetbrains.webm" type="video/webm">
+    <source src="/assets/video/appmap-license-key-jetbrains.mp4" type="video/mp4">
+  </video>
+</div>
+
+<script>
+  function JetBrainsplayVideo() {
+    var video = document.getElementById('JetBrainsvideoPlayer');
+    var placeholder = document.getElementById('JetBrainsvideoPlaceholder');
+    placeholder.style.display = 'none';
+    video.style.display = 'block';
+    video.play();
+  }
+</script>

package/built/docs/reference/navie.md

@@ -0,0 +1,261 @@
+---
+layout: docs
+title: Docs - Reference
+description: "Reference Guide to AppMap Navie, including advanced usage and configuration"
+toc: true
+reference: true
+name: AppMap Navie AI
+step: 3
+---
+
+# AppMap Navie AI
+- [Advanced Navie Commands](#advanced-navie-commands)
+  - [`@explain`](#explain)
+  - [`@help`](#help)
+  - [`@generate`](#generate)
+- [Bring Your Own Model Examples](#bring-your-own-model-examples)
+  - [OpenAI](#openai)
+  - [Azure OpenAI](#azure-openai)
+  - [AnyScale Endpoints](#anyscale-endpoints)
+  - [Ollama](#ollama)
+  - [LM Studio](#lm-studio)
+- [OpenAI Key Management in VS Code](#openai-key-management-in-vs-code)
+  - [Add a new OpenAI Key in VS Code](#add-a-new-openai-key-in-vs-code)
+  - [Delete a configured OpenAI Key](#delete-a-configured-openai-key)
+  - [How is my API key saved securely?](#how-is-my-api-key-saved-securely)
+- [OpenAI Key Management in JetBrains](#openai-key-management-in-jetbrains)
+  - [Adding or Modifying OpenAI API Key in JetBrains](#adding-or-modifying-openai-api-key-in-jetbrains)
+  - [How is my API key saved securely?](#how-is-my-api-key-saved-securely-1)
+- [Accessing Navie Logs](#accessing-navie-logs)
+  - [In VS Code](#in-vs-code)
+  - [In JetBrains](#in-jetbrains)
+- [GitHub Repository](#github-repository)
+
+## Advanced Navie Commands
+
+You can ask free-form questions, or start your question with one of these commands:
+
+- [`@explain`](#explain)
+- [`@help`](#help)
+- [`@generate`](#generate)
+
+### `@explain`
+
+The `@explain` command prefix within Navie serves as a default option focused on helping you learn more about your project. Using the `@explain` prefix will focus the Navie AI response to be more explanatory and will dive into architectural level questions across your entire code base. You can also use this to ask for ways to improve the performance of a feature as well. 
+
+#### Examples <!-- omit in toc -->
+
+- @explain how does user authentication work in this project?
+- @explain how is the export request for physical flows handled, and what are the tables involved?
+- @explain how does the products listing page works and how can I improve the performance?
+
+### `@help`
+
+Navie will help you setup AppMap, including generating AppMap recordings and diagrams.  This prefix will focus the Navie AI response to be more specific towards help with using AppMap products and features.  This will leverage the [AppMap documentation](https://appmap.io/docs) as part of the context related to your question and provide guidance for using AppMap features or diving into advanced AppMap topics. 
+
+#### Examples <!-- omit in toc -->
+
+- @help how do I setup process recording for my node.js project?
+- @help how can I reduce the size of my large AppMap Data recordings?
+- @help how can i export my AppMap data to atlassian confluence? 
+
+
+### `@generate`
+
+The `@generate` prefix will focus the Navie AI response to optimize for new code creation.  This is useful when you want the Navie AI to respond with code implementations across your entire code base. This is useful for both creation of new code as well as creation of test cases. 
+
+#### Examples <!-- omit in toc -->
+
+- @generate Using the django-simple-captcha library add the necessary code for an offline captcha to my new user registration page.
+- @generate Update the function for the physical flow export to include data type via physical_spec_data_type and physical_specification tables without changing the existing functionality.
+- @generate Design and implement a cache key for user posts and show me how to implement it within this code base
+
+## Bring Your Own Model Examples
+
+### OpenAI
+
+**Note:** We recommend configuring your OpenAI key using the code editor extension. Follow the [Bring Your Own Key](/docs/navie/bring-your-own-model.html#configuring-your-openai-key) docs for instructions.  
+
+Only `OPENAI_API_KEY` needs to be set, other settings can stay default:
+
+| `OPENAI_API_KEY`| `sk-9spQsnE3X7myFHnjgNKKgIcGAdaIG78I3HZB4DFDWQGM` |
+
+When using your own OpenAI API key, you can also modify the OpenAI model for Navie to use.  For example if you wanted to use `gpt-3.5` or use an preview model like `gpt-4-vision-preview`.
+
+| `APPMAP_NAVIE_MODEL`| `gpt-4-vision-preview` |
+
+### Azure OpenAI
+
+Assuming you [created](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/create-resource) a `navie` GPT-4 deployment on `contoso.openai.azure.com` OpenAI instance:
+
+| `AZURE_OPENAI_API_KEY` | `e50edc22e83f01802893d654c4268c4f` |
+| `AZURE_OPENAI_API_VERSION` | `2024-02-01` |
+| `AZURE_OPENAI_API_INSTANCE_NAME` | `contoso` |
+| `AZURE_OPENAI_API_DEPLOYMENT_NAME` | `navie` |
+
+### AnyScale Endpoints
+
+[AnyScale Endpoints](https://www.anyscale.com/endpoints) allows querying a
+selection of open-source LLMs. After you create an account you can use it by
+setting:
+
+| `OPENAI_API_KEY` | `esecret_myxfwgl1iinbz9q5hkexemk8f4xhcou8` |
+| `OPENAI_BASE_URL` | `https://api.endpoints.anyscale.com/v1` |
+| `APPMAP_NAVIE_MODEL` | `mistralai/Mixtral-8x7B-Instruct-v0.1` |
+
+Consult [AnyScale documentation](https://docs.endpoints.anyscale.com/) for model
+names. Note we recommend using Mixtral models with Navie.
+
+### Ollama
+
+You can use [Ollama](https://ollama.com/) to run Navie with local models; after
+you've successfully ran a model with `ollama run` command, you can configure
+Navie to use it:
+
+| `OPENAI_API_KEY` | `dummy` |
+| `OPENAI_BASE_URL` | `http://127.0.0.1:11434/v1` |
+| `APPMAP_NAVIE_MODEL` | `mixtral` |
+
+**Note:** Even though it's running locally a dummy placeholder API key is still required.
+
+### LM Studio
+
+You can use [LM Studio](https://lmstudio.ai/) to run Navie with local models. 
+
+After downloading a model to run, select the option to run a local server.
+
+<img class="video-screenshot" src="/assets/img/product/lmstudio-run-local-server.webp"/> 
+
+In the next window, select which model you want to load into the local inference server.
+
+<img class="video-screenshot" src="/assets/img/product/lmstudio-load-model.webp"/> 
+
+After loading your model, you can confirm it's successfully running in the logs.  
+
+*NOTE*: Save the URL it's running under to use for `OPENAI_BASE_URL` environment variable.
+
+For example: `http://localhost:1234/v1`
+
+<img class="video-screenshot" src="/assets/img/product/lmstudio-confirm-running.webp"/>
+
+In the `Model Inspector` copy the name of the model and use this for the `APPMAP_NAVIE_MODEL` environment variable.
+
+For example: `Meta-Llama-3-8B-Instruct-imatrix`
+
+<img class="video-screenshot" src="/assets/img/product/lmstudio-model-inspector.webp"/>
+
+Continue to configure your local environment with the following environment variables based on your LM Studio configuration.  Refer to the [documentation above](#bring-your-own-model-byom) for steps specific to your code editor.
+
+| `OPENAI_API_KEY` | `dummy` |
+| `OPENAI_BASE_URL` | `http://localhost:1234/v1` |
+| `APPMAP_NAVIE_MODEL` | `Meta-Llama-3-8B-Instruct-imatrix` |
+
+**Note:** Even though it's running locally a dummy placeholder API key is still required.
+
+## OpenAI Key Management in VS Code
+
+### Add a new OpenAI Key in VS Code 
+
+The standard way to add an OpenAI API key in VS Code is to use the `gear` icon in the Navie chat window, but you can alternatively set the key using the VS Code Command Palette with an `AppMap` command option.
+
+In VS Code, open the Command Palette.
+
+You can use a hotkey to open the VS Code Command Palette
+   - Mac: `Cmd + Shift + P`
+   - Windows/Linux: `Ctrl + Shift + P`
+
+Or you can select `View` -> `Command Palette`
+
+<img class="video-screenshot" src="/assets/img/product/byok-command-palette.webp"/> 
+
+Search for `AppMap Set OpenAPI Key`
+
+<img class="video-screenshot" src="/assets/img/product/byok-search.webp"/> 
+
+Paste your key into the new field and hit enter.
+
+You'll get a notification in VS Code that your key is set. 
+
+**NOTE:** You will need to reload your window for the setting to take effect. Use the Command Palette `Developer: Reload Window`
+
+<img class="video-screenshot" src="/assets/img/product/byok-key-set.webp"/> 
+
+### Delete a configured OpenAI Key
+
+To delete your key, simply open the Command Palette
+
+You can use a hotkey to open
+   - Mac: `Cmd + Shift + P`
+   - Windows/Linux: `Ctrl + Shift + P`
+
+Or you can select `View` -> `Command Palette`
+
+<img class="video-screenshot" src="/assets/img/product/byok-command-palette.webp"/> 
+
+Search for `AppMap Set OpenAPI Key`
+
+<img class="video-screenshot" src="/assets/img/product/byok-search.webp"/> 
+
+And simply hit enter with the field blank.  VS Code will notify you that the key has been unset.
+
+**NOTE:** You will need to reload your window for the setting to take effect. Use the Command Palette `Developer: Reload Window`
+
+<img class="video-screenshot" src="/assets/img/product/byok-key-erased.webp"/> 
+
+### How is my API key saved securely?
+
+For secure storage of API key secrets within AppMap, we use the default VS Code secret storage which leverages  Electron's safeStorage API to ensure the confidentiality of sensitive information. Upon encryption, secrets are stored within the user data directory in a SQLite database, alongside other VS Code state information. This encryption process involves generating a unique encryption key, which, on macOS, is securely stored within `Keychain Access` under "Code Safe Storage" or "Code - Insiders Safe Storage," depending on the version. This method provides a robust layer of protection, preventing unauthorized access by other applications or users with full disk access. The safeStorage API, accessible in the main process, supports operations such as checking encryption availability, encrypting and decrypting strings, and selecting storage backends on Linux. This approach ensures that your secrets are securely encrypted and stored, safeguarding them from potential threats while maintaining application integrity.
+
+## OpenAI Key Management in JetBrains
+
+The standard way to add an OpenAI API key in JetBrains is to use the `gear` icon in the Navie chat window, but you can alternatively set the key directly in the JetBrains settings. 
+
+### Adding or Modifying OpenAI API Key in JetBrains
+
+In JetBrains, open the `Settings` option. 
+
+![Open View in VS Code](/assets/img/docs/jetbrains-settings-1.webp)
+
+In the `Settings` window, search for `appmap` in the search bar on the side.  Under the `Tools -> AppMap` you will see a configuration option for your OpenAI API Key in the `AppMap Services` section.  This is the same section you are able to add/edit/modify your other environment settings for using your own custom models. 
+
+![Open View in VS Code](/assets/img/docs/jetbrains-settings-2.webp)
+
+### How is my API key saved securely?
+
+AppMap follows JetBrains best practices for the storing of sensitive data. The AppMap JetBrains plugin uses the `PasswordSafe` package [to securely persist](https://www.jetbrains.com/help/idea/reference-ide-settings-password-safe.html) your OpenAI API key.  The default storage format for `PasswordSafe` is operating system dependent. Refer to the [JetBrains Developer Documents](https://plugins.jetbrains.com/docs/intellij/persisting-sensitive-data.html#storage) for more information. 
+
+## Accessing Navie Logs
+
+### In VS Code
+
+You can access the Navie logs in VS Code by opening the `Output` tab and selecting `AppMap Services` from the list of available output logs.  
+
+To open the Output window, on the menu bar, choose View > Output, or in Windows press `Ctrl+Shift+U` or in Mac use `Shift+Command+U`
+
+![Open View in VS Code](/assets/img/docs/vscode-output-1.webp)
+
+Click on the output log dropdown in the right corner to view a list of all the available output logs. 
+
+![Open Output logs list](/assets/img/docs/vscode-output-2.webp)
+
+Select on the `AppMap: Services` log to view the logs from Navie. 
+
+![Select AppMap Services](/assets/img/docs/vscode-output-3.webp)
+
+### In JetBrains
+
+You can enable debug logging of Navie in your JetBrains code editor by first opening `Help` > `Diagnostic Tools` > `Debug Log Settings`. 
+
+![JetBrains Debug Log menu](/assets/img/jetbrains-debug-logs.webp)  
+
+In the `Custom Debug Log Configuration` enter `appland` to enable DEBUG level logging for the AppMap plugin. 
+
+![JetBrains Debug Log Configuration](/assets/img/jetbrains-logging-configuration.webp)  
+
+Next, open `Help` > `Show Log...` will open the IDE log file. 
+
+![JetBrains Debug Show Log](/assets/img/jetbrains-show-log.webp)
+
+## GitHub Repository
+
+[https://github.com/getappmap/appmap](https://github.com/getappmap/appmap)

package/built/docs/reference/remote-recording-api.md

@@ -0,0 +1,97 @@
+---
+layout: docs
+title: Docs - Reference
+description: "Learn how to use the AppMap Remote Recording API to start, stop, and save AppMap Data. AppMap agent handles requests on the same port as the app."
+toc: false
+reference: true
+name: Remote recording API
+step: 11
+redirect_from: [/docs/reference/remote-recording]
+---
+
+# Remote recording API <!-- omit in toc -->
+
+- [Start a remote recording](#start-a-remote-recording)
+- [Retrieve the current recording status](#retrieve-the-current-recording-status)
+- [Stop a remote recording](#stop-a-remote-recording)
+- [Save recorded AppMap Data to disk](#save-recorded-appmap-data-to-disk)
+
+When an application is set up for AppMap recording, the AppMap agent injects itself into the web stack and handles the remote recording HTTP requests, accepting requests on the same port as the web interface of the application.
+
+For example, if you deployed your application to a local Tomcat server listening on port 8080, call the remote recording endpoints at `http://localhost:8080/_appmap/*` 
+
+##  Start a remote recording
+
+```
+POST /_appmap/record
+```
+{: .example-code}
+
+No payload in the request is expected.
+
+This endpoint returns `200` if a new recording session was started successfully or `409` if an existing recording session was already in progress. It returns an empty body in the response.
+
+**curl example:**
+
+```
+curl -H 'Accept: application/json' -sXPOST http://localhost:8080/_appmap/record
+```
+
+## Retrieve the current recording status
+
+```
+GET /_appmap/record
+```
+{: .example-code}
+
+No payload in the request is expected.
+
+This endpoint returns status `200` .
+
+AppMap recording status is returned in the response body, the "enabled" property is set to `true` when recording is in progress:
+
+```
+Content-type: application/json
+{
+  "enabled": boolean
+}
+```
+
+**curl example:**
+
+```
+curl -H 'Accept: application/json' -sXGET http://localhost:8080/_appmap/record
+```
+
+## Stop a remote recording
+
+```
+DELETE /_appmap/record
+```
+{: .example-code}
+
+No payload in the request is expected.
+
+This method returns `200` If an active recording session was stopped successfully, and the body contains AppMap JSON, or `404` If there was no active recording session to be stopped.
+
+If successful, the recorded AppMap is returned in the response body.
+
+```
+Content-type: application/json
+{
+  "version": "1.x",
+  "metadata": {},
+  "classMap": [],
+  "events": [],
+}
+```
+
+**curl example:**
+```
+curl -H 'Accept: application/json' -sXDELETE http://localhost:8080/_appmap/record -o MyFirstAppMap.appmap.json
+```
+
+## Save recorded AppMap Data to disk
+
+Save the returned payload to disk as an `.appmap.json` file. We recommend that the AppMap file be named after the recorded test and that additional metadata is added to the recorded AppMap prior to saving, such as the AppMap’s name or labels indicating the test outcome and framework. See the [AppMap specification](https://github.com/getappmap/appmap#appmap-data-specification) for details about AppMap metadata.
+