diff --git a/docs/appmap-overview.md b/docs/appmap-overview.md deleted file mode 100644 index 8e7b61ef3f..0000000000 --- a/docs/appmap-overview.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -layout: docs -toc: true -title: Docs - AppMap overview -description: "Explore AppMap, an open-source code analysis tool capturing code execution traces as interactive diagrams, ideal for web frameworks like Rails, Django, and Flask." -redirect_from: [/docs, /docs/faq] - ---- -# AppMap overview - -AppMap is an open-source runtime code analysis tool. - -AppMap records code execution traces, collecting information about how your code works and what it does. Then it presents this information as interactive diagrams that you can search and navigate. In the diagrams, you can see exactly how functions, web services, data stores, security, I/O, and dependent services all work together when application code runs. - -You use AppMap Data right in your code editor, using an AppMap extension or plugin. AppMap Data also link directly to code, so you can use the information in the diagrams to make immediate code changes and improvements. - -Over 85,000 software developers are using the [AppMap extension for VSCode](https://marketplace.visualstudio.com/items?itemName=appland.appmap) and the [AppMap plugin for JetBrains](https://plugins.jetbrains.com/plugin/16701-appmap). - -Get Started with AppMap - -![Getting started screenshot](/assets/img/docs/dependency-map-example.webp) -_AppMap dependency map in Visual Studio Code_ - -## What kind of code does it work with? - -AppMap works best with web application and API frameworks, such as Rails, Django, Flask, Express, and Spring. That's because AppMap has specialized features for mapping web services, routing, view templates, HTTP client requests, caching, authentication, and SQL. You can map any kind of project that's written in a supported language, but it's when you map a database-backed web application or API service that you'll see the full power of AppMap. - -AppMap works equally well with small and large projects - monoliths and microservices. And by large, we mean large. AppMap has been used successfully on code bases with 10 million lines of code. For a project that large, AppMap is a truly game-changing way to understand what the code is doing, from the front-end templates and web services, through the classes and functions, through SQL and HTTP client requests, and back. - -{% include docs/app_framework_logos.html %} - -## What can I use it for? - -**Help new developers get oriented by creating a library of key AppMap Diagrams** - -If you're an expert on a code base, you can create AppMap Data that will help other developers to learn how the code works, ramp up quickly, and contribute. Start collecting AppMap Data of key flows into a project Wiki or README. Then, when you get questions about the code base, you can direct developers there to get "self-service" code onboarding help from these diagrams. - -**Use AppMap Data to add context to bug reports and other code issues** - -If you find a bug or security flaw, you can record AppMap Data and attach it to the code issue/ticket. The AppMap Data will be a massive help to the developer who takes on the task of finding and fixing the bug. Developers, security testers, and QA people can all help make bug fixing easier by recording and submitting AppMap Data to the dev team. - - -**Use AppMap Data to learn new-to-you code** - -If you're new to a code base, you can ask a code expert to provide you with AppMap Diagrams that will orient you to the work you've been asked to do. The code expert can direct you to a Wiki or README that has AppMap Diagrams of key flows. Or, the code expert can make you a custom AppMap Diagram - and then you can return the favor by contributing the AppMap Diagram to the project Wiki or README, along with some of your own thoughts about how to use it. - -## Features - -* **Code execution recording** AppMap agent libraries record executing code and save the data as JSON files. Running test cases is the most common way to record AppMap Data, but it’s not the only way. You can find additional examples of how to generate AppMap Data in the [Recording AppMap Data](/docs/recording-methods.html) documentation. -* **Interactive diagrams** Sequence Diagrams, Flame Graphs, and Dependency maps are created automatically, showing how the modules and packages in your code relate to each other for a specific AppMap. A Trace diagram shows the code execution tree, including web services, functions, SQL queries, parameter values, status codes, etc. Learn more about [AppMap Diagrams](/docs/guides/using-appmap-diagrams). -* **SQL query data** AppMap records all SQL queries that your application makes. Whether a query is listed explicitly in the code, or automatically generated by an object-relational mapping (ORM) library, you can see exactly what’s happening between your code and the database. Learn more about [how to read SQL in AppMap Diagrams](/docs/guides/reading-sql-in-appmap-diagrams) -* **Web services data** AppMap records all HTTP server requests that are handled by your application. The AppMap includes the request method, path, headers, parameters, and status code, so you can see exactly what message your application received, and how it responded. AppMap captures so much information about HTTP server requests that it can automatically generate a complete OpenAPI (aka Swagger) file for your application. Learn more about [generating the OpenAPI description file](/docs/openapi). -* **Code labels** You can apply labels to the most important functions in your code. You can quickly identify and locate the most important functions in each code path by searching for labels in AppMap Diagrams. Labels are maintained right in the code base using annotations (Java and Python) or code comments (Ruby). Because labels are in the code, all developers can collaborate on labeling, and the code is always the source of truth for labels. -* **Open source** AppMap agent libraries and UI code are all available as MIT License open source. Learn about [Open Source contributions and our community](/docs/community.html). - diff --git a/docs/diagrams/dependency-map.md b/docs/diagrams/dependency-map.md deleted file mode 100644 index 883cf8a079..0000000000 --- a/docs/diagrams/dependency-map.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -layout: docs -title: Docs - AppMap Diagrams - Dependency Map -description: "Explore AppMap's interactive Dependency Map for a comprehensive view of your code's connections. Navigate through web services, libraries, SQL, and more." -diagrams: true -name: Dependency Map -step: 2 ---- - -# Dependency Map -The Dependency Map diagram shows all the code that's relevant to what you're working on and how it's connected. Here you can search and navigate through web services, code, libraries, dependency services, and SQL, all in the context of a specific feature. - -The dependency map is fully interactive. You can: -- [Expand and collapse packages and Web Service endpoints](#expand-and-collapse-packages-and-web-service-endpoints) -- [View detailed information about dependencies and classes](#view-detailed-information-about-dependencies-and-classes) -- [List the functions of a class that are used by the executed code](#list-the-functions-of-a-class-that-are-used-by-the-executed-code) -- [Explore callers and callees](#explore-callers-and-callees) -- [View SQL queries in dependency map](#view-sql-queries-in-dependency-map) -- [Open source code right to the line of any particular function.](#open-source-code-right-to-the-line-of-any-particular-function) - -![Dependency map overview](/assets/img/docs/dependency-map-overview.webp "Dependency map overview") - -#### Expand and collapse packages and Web Service endpoints: -
- -
- -#### View detailed information about dependencies and classes: -
- -
- -#### List the functions of a class that are used by the executed code: -
- -
- - -#### Explore callers and callees: -
- -
- -#### View SQL queries in dependency map: -
- -
- -#### Open source code right to the line of any particular function: -
- -
diff --git a/docs/diagrams/flamegraph.md b/docs/diagrams/flamegraph.md deleted file mode 100644 index 5879f1d067..0000000000 --- a/docs/diagrams/flamegraph.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -layout: docs -title: Docs - Diagrams -description: "Explore AppMap's Flame Graphs, a tool for visualizing code performance. Learn how to read, drill down, and switch views to identify performance issues." -diagrams: true -name: Flame Graph -step: 5 ---- - -# Flame Graph - -- [How to read a Flame Graph](#how-to-read-a-flame-graph) -- [Drilling Down](#drilling-down) -- [Switching to Other Views](#switching-to-other-views) -- [Identifying Performance Issues](#identifying-performance-issues) - - [Expensive functions and queries](#expensive-functions-and-queries) - - [N+1 Queries](#n1-queries) - - [Delays from external service calls](#delays-from-external-service-calls) - -Flame Graphs visualize the performance of your application’s code. A Flame Graph shows the time spent in each part of your application’s call stack, where the width of the event is proportional to how long it takes to execute. - -Flame Graphs make it easy to see how much time is spent in each function, and which calls are the most expensive. - -![flame graph image](/assets/img/docs/flamegraph-5.webp) - -## How to read a Flame Graph - -The lowest layer in a Flame Graph represents the AppMap, and it contains the map’s name. For AppMaps created from tests, this will usually be the same name as the test from which it was generated. In the example below, the AppMap was recorded from a test related to an application’s account activation capability. - -![flame graph image](/assets/img/docs/flamegraph-8.webp) - -Events in a Flame Graph are ordered bottom-up for functions calling other functions, and left-to-right for subsequent calls. To illustrate, the events in the map below are numbered according to the sequence in which they occurred. - -![flame graph image](/assets/img/docs/flamegraph-9.png) - -Cells in the flame graph are colored similarly to how they appear in the other AppMap views like the Dependency Map and Sequence Diagram. Blue represents classes, purple represents database queries, and yellow represents outgoing calls to other services. The lowest level of the Flame Graph, the map name, is colored teal. - -Each event cell also shows the elapsed time spent executing it. This may be displayed in ms (milliseconds) or µ (microseconds). - -![flame graph image](/assets/img/docs/flamegraph-4.png) - -Timing data and event names may not always fit on small cells. These can be revealed by hovering your mouse pointer over the cell. - -## Drilling Down - -It can be useful to zoom into particular parts of the call stack to examine the performance of certain functions more closely. Clicking on any event will expand it to the full width, allowing you to more clearly see the functions which it called. - -
- -
- -You can also drill deeper into the Flame Graph using the zoom control on the right by clicking on the `+` and `-` controls, or by dragging the zoom bar. You can also zoom using your mouse wheel, and the graph will zoom towards the position of your mouse pointer. - -
- -
- -AppMap filter settings also apply to Flame Graphs. For example, if you decide to hide calls to certain types of events (for example, by excluding calls to a logging package) those events will not appear in the Flame Graph. - -## Switching to Other Views - -While investigating an event in an application, you can also view the same event in the Sequence Diagram and Trace View diagrams. Click on the event in question, and then select either “Show in Sequence” or “Show in Trace”. - -Similarly, you can select an event in a Sequence Diagram or Trace View and click “Show in Flame Graph” to see it displayed in a Flame Graph diagram. - -![flame graph image](/assets/img/docs/flamegraph-7.gif) - -## Identifying Performance Issues - -Certain performance problems can be visually easier to spot with a Flame Graph. - -#### Expensive functions and queries - -Expensive functions are those that are slow due to them doing a lot of computation and not spending much time waiting on other functions to return. In the example graph shown below, the function at the bottom of the stack is spending most of its 15.1 milliseconds of time waiting for the functions and queries which it called to return. The most expensive area in this stack is therefore the SQL `SELECT` query at the top which takes 10.3 milliseconds. That query should likely be the focus of any performance optimization effort over the other functions and queries. - -![flame graph image](/assets/img/docs/flamegraph-expensive.png) - -#### N+1 Queries - -AppMap Analysis automatically detects [N+1 queries](/docs/reference/analysis-rules#n-plus-one-query), which are identical database queries called by the same parent function. In the example graph below, 60 repeated queries are visible at the top of the call stack. - -![flame graph image](/assets/img/docs/flamegraph-1.gif) - -#### Delays from external service calls - -Performance problems can sometimes be caused by latency in external services. In the example graph below, the event in yellow represents a call to another service using HTTP. The call took 936 milliseconds to return, and only a few milliseconds more for the calling function to deal with that. Any optimization efforts for this area should therefore be spent in that other application, preferably by generating an AppMap for its `/users` API. - -![flame graph image](/assets/img/docs/flamegraph-external-svc.png) diff --git a/docs/diagrams/how-it-works.md b/docs/diagrams/how-it-works.md deleted file mode 100644 index 8ff9e1a5cd..0000000000 --- a/docs/diagrams/how-it-works.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -layout: docs -title: Docs - Diagrams -description: "AppMap visualizes code behavior in interactive diagrams. Features include recording dynamic runtime code with AppMap, quick search in navigation, filtering, detailed stats, and sequence diagram control." -diagrams: true -name: How it works -step: 1 -redirect_from: [/docs/how-to-use-appmap-diagrams.html, /docs/how-to-use-appmap-diagrams, /docs/diagrams/how-to-use-appmaps] ---- - -# How it works - -AppMap records the behavior of running code into JSON files, and visualizes them in interactive diagrams right in your code editor. - -{% include docs/how_it_works_illo.html %} - -## AppMap agent records executing code as JSON files -Once your app is instrumented, the AppMap agent creates JSON files as you execute test cases, run sample programs, or perform interactive sessions with your app. - -AppMap files can be most conveniently recorded from automated tests, but other methods of recording are preferred in certain situations, such as direct recording of code blocks or remote recording controlled with REST endpoints. [Learn more about Recording AppMaps](/docs/recording-methods). - -## Quick search for HTTP routes, packages, classes, and functions in the left-hand navigation bar - -Use the navigation bar for quick navigation to items of interest, for example, HTTP routes, labels, packages, classes, functions. - -
- -
- -## Use the filtering icon to reduce the number of objects in the AppMap view - -Filter out items such as unlabeled code, specific classes or packages, external code, and more. - -
- -
- -## Show more detailed statistics about your AppMap - -Includes the frequency of specific function calls and the size represented within the AppMap. This is helpful when [handling large AppMaps](https://appmap.io/docs/guides/handling-large-appmaps.html) and to reduce their size. - - - -## Expand and Collapse the Depth of Sequence Diagrams - -This will hide or show all actions that are deeper in the call stack than the selected value, and will result in a more compact diagram. Actions can be expanded or collapsed with the `+` or `-` controls to change the depth of the calls shown within your sequence diagram. - -
- -
- -## Demo of using AppMaps -This video demonstrates how to use AppMap Diagrams when learning how unfamiliar code works: - -
\ No newline at end of file diff --git a/docs/diagrams/index.md b/docs/diagrams/index.md deleted file mode 100644 index f9472f6b19..0000000000 --- a/docs/diagrams/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: docs -title: Docs - Diagrams -description: "AppMap generates interactive diagrams from code execution traces, aiding in understanding and improving your code. Accessible right in your code editor, AppMap supports multiple frameworks." -toc: false ---- - -# Using AppMap Diagrams - -AppMap records code execution traces, collecting information about how your code works and what it does. Then it presents this information as interactive diagrams that you can search and navigate. In the diagrams, you can see exactly how functions, web services, data stores, security, I/O, and dependent services all work together when application code runs. - -You use AppMaps right in your code editor, using an AppMap extension or plugin. AppMaps also link directly to code, so you can use the information in the diagrams to make immediate code changes and improvements. - -- [How it works](/docs/diagrams/how-it-works) -- [Dependency Map](/docs/diagrams/dependency-map) -- [Trace View](/docs/diagrams/trace-view) -- [Sequence Diagram](/docs/diagrams/sequence-diagram) -- [Flame Graph](/docs/diagrams/flamegraph) - -#### AppMap is optimized for these frameworks: -{% include docs/app_framework_logos.html %} diff --git a/docs/diagrams/sequence-diagram.md b/docs/diagrams/sequence-diagram.md deleted file mode 100644 index 804666c4ee..0000000000 --- a/docs/diagrams/sequence-diagram.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -layout: docs -title: Docs - Diagrams -description: "Improve your software engineering with AppMap's interactive sequence diagrams. Generate, view, compare, and export diagrams directly in your code editor for accurate, up-to-date documentation." -diagrams: true -name: Sequence Diagram -step: 4 -redirect_from: [/docs/diagrams/sequence-diagrams] ---- - -# Sequence Diagram - -> “A sequence diagram shows [process](https://en.wikipedia.org/wiki/Process_(computing)) interactions arranged in time sequence in the field of [software engineering](https://en.wikipedia.org/wiki/Software_engineering). It depicts the processes involved and the sequence of messages exchanged between the processes needed to carry out the functionality.“[^1] - -The Sequence Diagram view shows an application's behavior in a linear chronological layout. Function calls are shown as horizontal arrows, ordered from top to bottom as they occurred at runtime. The elements in the sequence diagram are interactive and can be selected, collapsed, and hidden. - -Sequence diagrams can also be exported as SVG files for easy sharing and collaboration. Similar AppMaps can also be compared in a sequence diagram "diff" to reveal changes in runtime behavior caused by a code update. - -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](https://www.omg.org/spec/UML/). - -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. - -## Viewing sequence diagrams in the code editor - -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. - -![Open sequence diagram](/assets/img/docs/find-sequence-diagram.webp "Open sequence diagram") - -Sequence Diagrams follow these conventions: -1. Inbound HTTP server requests (if any) will be on the left hand side -2. Database queries and RPC requests (e.g. HTTP client requests) (if any) will be on the right hand side. -3. Each code package is represented as a sequence diagram “lifeline”. Each lifeline is a vertical lane which you can follow down the page. -4. Each function call is represented as a line from one lifeline to another. -5. The function return value (if any) will be depicted in the opposite direction. -6. If an AppMap contains HTTP server requests, other “root” events which are not HTTP server requests will be filtered out, by default. - -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. - -### Removing lifelines from view - -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. - -![Hide lifeline in sequence diagram](/assets/img/docs/hide-lifeline-sequence-diagram.webp "Hide lifeline in sequence diagram") - -Lifelines that have been hidden can be re-shown using the "Filters" control, or by resetting the map using the "Clear" control. - -![Show lifeline in sequence diagram](/assets/img/docs/show-lifeline-sequence-diagram.webp "Show lifeline in sequence diagram") - -### Collapsing sections of a Sequence Diagram - -Function calls that contain other events can be collapsed to make the diagram easier to read. This is done using the `[-]` control. - -![Collapse sequence diagram](/assets/img/docs/collapse-sequence-diagram.gif "Collapse sequence diagram") - -Clicking on the `[+]` control will expand the same sequence set once again. - -### Exporting sequence diagrams as SVG files - -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. - -![Export sequence diagram](/assets/img/docs/export-sequence-diagram.webp "Export sequence diagram") -![Save sequence diagram](/assets/img/docs/save-sequence-diagram.webp "Save sequence diagram") - -## 3rd Party Integrations - -Refer to the AppMap [integration documentation](/docs/integrations/plantuml) to learn more about how to integrate Sequence Diagrams with PlantUML and other 3rd party tools. - - -### Notes - -[^1]: - [https://en.wikipedia.org/wiki/Sequence_diagram](https://en.wikipedia.org/wiki/Sequence_diagram) \ No newline at end of file diff --git a/docs/diagrams/trace-view.md b/docs/diagrams/trace-view.md deleted file mode 100644 index ae669fd52a..0000000000 --- a/docs/diagrams/trace-view.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -layout: docs -title: Docs - AppMap Diagrams - Trace View -description: "Explore AppMap's interactive Trace view diagram. Navigate execution traces, view variable details, and link to source code." -diagrams: true -name: Trace View -step: 3 ---- - -# Trace View - -The Trace view diagram shows all the details of how a feature works. Here you can navigate forward, backward, up, and down through a detailed execution trace. See the call tree starting with web service endpoints going through function calls all the way to SQL operations. At any point, you can move quickly back and forth between the Trace view and your source code. - -The Trace view is fully interactive. You can: -- [Expand and collapse execution paths](#expand-and-collapse-execution-paths) -- [Explore callers and callees](#explore-callers-and-callees) -- [View variable names and values at any point in the code flow](#view-variable-names-and-values-at-any-point-in-the-code-flow) -- [View SQL queries](#view-sql-queries) -- [Open source code right to the line of any particular function](#open-source-code-right-to-the-line-of-any-particular-function) - -![Trace view is fully interactive](/assets/img/docs/trace-is-fully-interactive.webp "Trace view is fully interactive") - -#### Expand and collapse execution paths -
- -
- -#### Explore callers and callees -
- -
- -#### View variable names and values at any point in the code flow -
- -
- -#### View SQL queries -
- -
- -#### Open source code right to the line of any particular function -
- -
diff --git a/docs/get-started-with-appmap/navie-ai-quickstart.md b/docs/get-started-with-appmap/navie-ai-quickstart.md index 72cae4f0d6..7e95e0a796 100644 --- a/docs/get-started-with-appmap/navie-ai-quickstart.md +++ b/docs/get-started-with-appmap/navie-ai-quickstart.md @@ -10,11 +10,18 @@ redirect_from: [/docs/setup-appmap-in-your-code-editor/navie-ai-quickstart] # AppMap Navie AI Quickstart +- [Choose your AI Provider (Optional)](#choose-your-ai-provider-optional) - [Open AppMap Navie AI](#open-appmap-navie-ai) - [Ask Navie about your App](#ask-navie-about-your-app) - [Improve Navie AI Responses with AppMap Data](#improve-navie-ai-responses-with-appmap-data) - [Next Steps](#next-steps) +## Choose your AI Provider (Optional) + +By default, Navie uses an AppMap proxy of the latest OpenAI supported AI models. If you would like to customize your own model, you can leverage a variety of other AI model providers such as [Azure OpenAI](https://appmap.io/docs/reference/navie#azure-openai), [Fireworks.ai](https://appmap.io/docs/reference/navie#fireworks-ai), [LM Studio](https://appmap.io/docs/reference/navie#lm-studio), and more. + +If you have an active GitHub Copilot subscription, you can use Navie with the [Copilot Lanauage Model](/docs/reference/navie#github-copilot-language-model) as a supported backend. Refer to the Navie Copilot documentation for instructions on how to enable. + ## Open AppMap Navie AI After you complete the installation of AppMap for your code editor. Open the Navie Chat Window to ask Navie about your application. diff --git a/docs/navie/bring-your-own-model.md b/docs/navie/bring-your-own-model.md index 3ed3d0ff37..dee31abf4d 100644 --- a/docs/navie/bring-your-own-model.md +++ b/docs/navie/bring-your-own-model.md @@ -12,72 +12,18 @@ redirect_from: [/docs/navie/bring-your-own-llm, /docs/navie/bring-your-own-key] # Bring Your Own LLM Model By default, when asking a question to Navie, your code editor will interact with the AppMap hosted proxy for OpenAI. If you have a requirement to bring your own key or otherwise use your own OpenAI account you can specify your own OpenAI key; this will cause Navie to connect to OpenAI directly, without AppMap proxy acting as an intermediate. -- [Navie AI Recommended Models](#navie-ai-recommended-models) + +You can also use any OpenAI API compatible LLM model either running locally or via a 3rd party provider. Finally, for VS Code users with an active GitHub Copilot subscription, you can leverage the Copilot Language Models as a supported Navie backend. Refer to the [Navie docs for more examples](/docs/reference/navie#bring-your-own-model-examples) of using alternative language models. - [Bring Your Own OpenAI API Key (BYOK)](#bring-your-own-openai-api-key-byok) - - [Configuring Your OpenAI Key](#configuring-your-openai-key) - - [Modify which OpenAI Model to use](#modify-which-openai-model-to-use) - - [Reset Navie AI to use Default Navie Backend](#reset-navie-ai-to-use-default-navie-backend) - [Bring Your Own Model (BYOM)](#bring-your-own-model-byom) - - [Configuration](#configuration) - - [Configuring in JetBrains](#configuring-in-jetbrains) - - [Configuring in VS Code](#configuring-in-vs-code) +- [Using GitHub Copilot Language Models](#using-github-copilot-language-models) - [Examples](#examples) -## Navie AI Recommended Models - -

-AppMap Navie AI recommends avoiding models that do not support chat mode. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Navie AI Backend LLMEase of SetupQuality of Responses
AppMap OpenAI Proxy (default)⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
Self Managed OpenAI API Key⭐⭐⭐⭐⭐⭐⭐⭐⭐
Azure Hosted OpenAI⭐⭐⭐⭐⭐⭐⭐⭐
Anyscale Hosted Mixtral-8x7B⭐⭐⭐⭐⭐⭐
Locally Hosted Mixtral-8x7B-Instruct-v0.1⭐⭐⭐⭐⭐
Codellama/Codeqwen❌ Not Supported❌ Not Supported
- ## Bring Your Own OpenAI API Key (BYOK) Navie AI uses the AppMap hosted proxy with an AppMap managed OpenAI API key. If you have requirements to use your existing OpenAI API key, you can configure that within AppMap. This will ensure all Navie requests will be interacting with your own OpenAI account. -### Configuring Your OpenAI Key +### Configuring Your OpenAI Key In your code editor, open the Navie Chat window. If the model displays `(default)`, this means that Navie is configured to use the AppMap hosted OpenAI proxy. Click on the gear icon in the top of the Navie Chat window to change the model. @@ -101,7 +47,7 @@ After your code editor reloads, you can confirm your requests are being routed t ![OpenAI location](/assets/img/product/navie-byok-openai-3.webp) -#### Modify which OpenAI Model to use +#### Modify which OpenAI Model to use AppMap generally uses the latest OpenAI models as the default, but if you want to use an alternative model like `gpt-3.5` or a preview model like `gpt-4-vision-preview` you can modify the `APPMAP_NAVIE_MODEL` environment variable after configuring your own OpenAI API key to use other OpenAI models. @@ -109,7 +55,7 @@ After setting your `APPMAP_NAVIE_MODEL` with your chosen model reload/restart yo ![JetBrains OpenAI key modal](/assets/img/product/custom-model.webp) -### Reset Navie AI to use Default Navie Backend +### Reset Navie AI to use Default Navie Backend At any time, you can unset your OpenAI API Key and revert usage back to using the AppMap hosted OpenAI proxy. Select the gear icon in the Navie Chat window and select `Use Navie Backend` in the modal. @@ -118,15 +64,13 @@ At any time, you can unset your OpenAI API Key and revert usage back to using th ## Bring Your Own Model (BYOM)

-This feature is in early access. We currently recommend GPT4-Turbo from OpenAI via OpenAI or Microsoft Azure, and Mixtral-8x7B-Instruct-v0.1. Refer to the AppMap Recommended Models documentation for more info + This feature is in early access. + We recommend choosing a model that is trained on a large corpus of both human-written natural language and code.

-Another option is to use a different LLM entirely; you can use any OpenAI-compatible model -running either locally or remotely. When configured like this, as in the BYOK case, -Navie won't contact the AppMap hosted proxy and your conversations will stay private -between you and the model. +Navie currently supports any OpenAI-compatible model running locally or remotely. When configured like this, as in the BYOK case, Navie won't contact the AppMap hosted proxy and your conversations will stay private between you and the model provider. -### Configuration +### Configuration In order to configure Navie for your own LLM, certain environment variables need to be set for AppMap services. @@ -148,7 +92,7 @@ For Azure OpenAI, you need to [create a deployment](https://learn.microsoft.com/ [Configuring in JetBrains](#configuring-byom-in-jetbrains) [Configuring in VS Code](#configuring-byom-in-vs-code) -### Configuring in JetBrains +### Configuring in JetBrains In JetBrains, go to settings. @@ -171,7 +115,7 @@ After reloading you can confirm the model is configured correctly in the Navie C -### Configuring in VS Code +### Configuring in VS Code #### Editing AppMap services environment @@ -193,6 +137,31 @@ After reloading you can confirm the model is configured correctly in the Navie C +## Using GitHub Copilot Language Models + +Starting with VS Code `1.91` and greater, and with an active GitHub Copilot subscription, you can use Navie with the Copilot Language Model as a supported LLM backend. This allows you to leverage the powerful runtime powered Navie AI Architect with your existing Copilot subscription. This is the recommended option for users in corporate environments where Copilot is the only approved and supported language model. + +### Requirements + +The following items are required to use the GitHub Copilot Language Model with Navie: + +- VS Code Version `1.91` or greater +- AppMap Extension version `v0.123.0` or greater +- GitHub Copilot VS Code extension must be installed +- Signed into an active paid or trial GitHub Copilot subscription + +#### Setup + +Open the VS Code Settings, and search for `navie vscode` + + + +Click the box to use the `VS Code language model...` + +After clicking the box to enable the VS Code LM, you'll be instructed to reload your VS Code to enable these changes. + +For more details about using the GitHub Copilot Language Model as a supported Navie backend, refer to the [Navie reference guide](/docs/reference/navie.html#github-copilot-language-model) + ## Examples Refer to the [Navie Reference Guide](/docs/reference/navie) for detailed examples of using Navie with your own LLM backend. diff --git a/docs/navie/using-navie.md b/docs/navie/using-navie.md index 9fb20bc645..9ba43fdd21 100644 --- a/docs/navie/using-navie.md +++ b/docs/navie/using-navie.md @@ -12,6 +12,7 @@ redirect_from: [/docs/guides/navie-best-practices] - [User Interface](#user-interface) - [Basic Layout](#basic-layout) +- [Navie Advanced Commands](#navie-advanced-commands) - [Navie Best Practices](#navie-best-practices) - [Create AppMap Data](#create-appmap-data) - [Ask Navie](#ask-navie) @@ -45,14 +46,24 @@ The Navie user interface consists of 5 key areas. section. +## Navie Advanced Commands + +Navie supports a variety of `@` prefixed commands you can use at the beginning of any question you ask. For example, you can use the `@plan` command to focus the Navie AI response to build a detailed architecture plan for a new feature. You can use the `@generate` command to create code to implement a Navie AI created plan. Navie supports a growing list of advanced commands which focus the AI responses towards completing the specific task requested. + +For more detailed documentation about the available Navie prefix commands available, refer to the [Navie Reference Documentation for Advanced Commands](https://appmap.io/docs/reference/navie.html#advanced-navie-commands). + ## Navie Best Practices To generate the highest quality responses from Navie, we recommend the following approach. -- [Create AppMap Data](#create-appmap-data) -- [Ask Navie](#ask-navie) -- [Write Code](#write-code) -- [Repeat](#repeat) +- [User Interface](#user-interface) +- [Basic Layout](#basic-layout) +- [Navie Advanced Commands](#navie-advanced-commands) +- [Navie Best Practices](#navie-best-practices) + - [Create AppMap Data](#create-appmap-data) + - [Ask Navie](#ask-navie) + - [Implement Generated Code](#implement-generated-code) + - [Repeat](#repeat) ### Create AppMap Data diff --git a/docs/reference/appmap-java.md b/docs/reference/appmap-java.md index f1be5ae742..59a1f4460a 100644 --- a/docs/reference/appmap-java.md +++ b/docs/reference/appmap-java.md @@ -22,7 +22,7 @@ step: 6 - [Requests recording in Spark Framework](#requests-recording-in-spark-framework) - [Remote recording](#remote-recording) - [Process recording](#process-recording) -- [Code Block Recording](#code-block-recording) +- [Code block recording](#code-block-recording) - [Configuration](#configuration) - [Annotations](#annotations) - [@Labels](#labels) @@ -34,7 +34,7 @@ step: 6 ## About -`appmap-agent` is a Java agent JAR for recording [AppMap Data](https://github.com/getappmap/appmap) of your code. +`appmap-agent` is a Java agent JAR for recording [AppMap Data](https://github.com/getappmap/appmap) of your code. {% include docs/what_is_appmap_snippet.md %} @@ -79,7 +79,7 @@ $ java -javaagent:$HOME/.appmap/lib/java/appmap.jar myapp.jar ### Requests recording in Spring Boot and Spring Web Framework For Spring Boot and Spring Web Framework applications, `appmap-java` installs a ServletListener during initialization that will create recordings. The listener starts the recording before the servlet's `service` method is called, and ends the recording once `service` returns. -For Spring Boot, `appmap-java` adds the listener when the Spring Application is initialized. +For Spring Boot, `appmap-java` adds the listener when the Spring Application is initialized. For Spring Web Framework, `appmap-java` adds the listener when Spring's servlet container is initialized. @@ -123,7 +123,7 @@ $ java -javaagent:$HOME/.appmap/lib/java/appmap.jar -jar target/*.jar Other related options such as `appmap.recording.file` and `appmap.recording.name` are also available. Consult the [Configuration](#configuration) section for details. -## Code Block Recording +## Code block recording You can use the Java function `com.appland.appmap.record.Recording#record` to record a specific span of code. With this method, you can control exactly what code is recorded, and where the recording is saved. @@ -168,7 +168,7 @@ packages: exclude: [ com.mycorp.myproject.MyClass#MyMethod ] - path: org.springframework.web shallow: true - exclude: + exclude: - org.springframework.web.util - path: java.util.logging methods: @@ -196,7 +196,7 @@ Each entry in the `packages` list is a YAML object which has the following keys: Default: `false`. * **methods** A list of YAML objects describing how specific methods should be handled. - * **class** a regular expressiom matching names of classes in the package + * **class** a regular expression matching names of classes in the package * **name** a regular expression matching names of methods in **class** that should be instrumented * **labels** (optional) a list of labels that should be applied to all matching methods. diff --git a/docs/reference/appmap-python.md b/docs/reference/appmap-python.md index 83935281c5..a330c38e31 100644 --- a/docs/reference/appmap-python.md +++ b/docs/reference/appmap-python.md @@ -20,7 +20,8 @@ step: 5 - [unittest](#unittest) - [Request recording](#request-recording) - [Remote recording](#remote-recording) -- [Code Block Recording](#code-block-recording) +- [Process recording](#process-recording) +- [Code block recording](#code-block-recording) - [Web framework support](#web-framework-support) - [Django](#django) - [Flask](#flask) @@ -248,7 +249,23 @@ To enable debugging support, ensure: **Note** Your application must be running in a supported web framework for remote recording to work. -## Code Block Recording +{% include vimeo.html id='973082886' %} + +## Process recording + +AppMap can record your entire Python application from start to finish. + +To create a process +recording, run your application with `appmap-python` and pass the flag `--record process` : + +```shell +$ appmap-python --record process +``` + +Alternatively, you can set `APPMAP_RECORD_PROCESS=true`, as described +[below](#process-recording-var). + +## Code block recording You can use `appmap.record` as a context manager to record a specific span of code. With this method, you can control exactly what code is recorded, and where the recording is saved. @@ -263,7 +280,7 @@ from pathlib import Path import appmap -output_directory = Path('tmp/appmap/codeblock') +output_directory = Path('tmp/appmap/code') output_directory.mkdir(parents=True, exist_ok=True) # Step 2: Ensure the directory exists timestamp = datetime.now().isoformat(timespec='seconds') @@ -281,8 +298,8 @@ with open(output_file, "w") as f: { "name": str(timestamp), "recorder": { - "type": "process", - "name": "process", + "type": "code", + "name": "code", }, }, ) @@ -313,7 +330,7 @@ appmap_dir: tmp/appmap you can generate a recording of the code ``` -% python record_sample.py +% appmap-python python record_sample.py % jq '.events | length' tmp/appmap/codeblock/*.appmap.json 6 % jq < tmp/appmap/codeblock/*.appmap.json | head -10 @@ -480,7 +497,7 @@ $ appmap-python --record remote flask --app main.app * `APPMAP_RECORD_REQUESTS` controls creation of request recordings created when a web framework processes HTTP requests. When unset or `true`, request recordings will be created, otherwise they will not. -* `APPMAP_RECORD_PROCESS` controls recording of the entire python process that loads the agent. When +*
`APPMAP_RECORD_PROCESS` controls recording of the entire python process that loads the agent. When `true`, recording starts when the agent is loaded. When the process exits, an AppMap will be created. diff --git a/docs/reference/jetbrains.md b/docs/reference/jetbrains.md index 85b395e08e..bb80b111a4 100644 --- a/docs/reference/jetbrains.md +++ b/docs/reference/jetbrains.md @@ -39,7 +39,7 @@ AppMap tool window actions: ## "Start with AppMap" for Java -**NOTE:** This section only applies to Java applications. +
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. @@ -51,6 +51,23 @@ You can also use this custom button to run a specific test or group of tests wit +### "Start with AppMap" button + +Use the "Start with AppMap" button to start your run configurations with AppMap enabled. + +For JetBrains versions ***2024.1 and earlier*** the "Start with AppMap" button is in the main toolbar. + + + +For JetBrains versions ***2024.2 and later*** the "Start with AppMap" button is located in a dropdown menu, accessible by clicking on the vertical dots. + + + + +### Demo video: Recording AppMap Data from a Java application + + + {% include vimeo.html id='916087828' %} ### Create AppMap Data from JUnit test runs diff --git a/docs/reference/navie.md b/docs/reference/navie.md index 3ff490afc1..a39334e385 100644 --- a/docs/reference/navie.md +++ b/docs/reference/navie.md @@ -10,13 +10,18 @@ step: 3 # AppMap Navie AI - [Advanced Navie Commands](#advanced-navie-commands) + - [`@plan`](#plan) + - [`@generate`](#generate) + - [`@test`](#test) - [`@explain`](#explain) + - [`@diagram`](#diagram) - [`@help`](#help) - - [`@generate`](#generate) - [Bring Your Own Model Examples](#bring-your-own-model-examples) + - [GitHub Copilot Language Model](#github-copilot-language-model) - [OpenAI](#openai) - [Azure OpenAI](#azure-openai) - [AnyScale Endpoints](#anyscale-endpoints) + - [Fireworks AI](#fireworks-ai) - [Ollama](#ollama) - [LM Studio](#lm-studio) - [OpenAI Key Management in VS Code](#openai-key-management-in-vs-code) @@ -35,9 +40,42 @@ step: 3 You can ask free-form questions, or start your question with one of these commands: +- [`@plan`](#plan) +- [`@generate`](#generate) +- [`@test`](#test) - [`@explain`](#explain) - [`@help`](#help) -- [`@generate`](#generate) + + +### `@plan` + +The `@plan` command prefix within Navie focuses the AI response on building a detailed implementation plan for the relevant query. This will focus Navie on only understanding the problem and the application to generate a step-by-step plan. This will generally not respond with code implementation details, consider using the `@generate` command which can implement code based on the plan. + +#### Examples + +- @plan improve the performance of my slow product listing page. +- @plan implement a cache key for my user posting on my social media application. +- @plan migrate the /users/setting API endpoint from SQL to MongoDB. + +### `@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 will reduce the amount of code explanation and generally the AI will respond only with the specific files and functions that need to be changed in order to implement a specific plan. + +#### Examples + +- @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 + +### `@test` + +The `@test` command prefix will focus the Navie AI response to optimize for test case creation, such as unit testing or integration testing. This prefix will understand how your tests are currently written and provide updated tests based on features or code that is provided. You can use this command along with the `@generate` command to create tests cases for newly generated code. + +#### Examples + +- @test create integration test cases for the user setting page that is migrated to mongodb. +- @test create unit and integration tests that fully support the updated cache key functionality. +- @test provide detailed test cases examples for testing the updated user billing settings dashboard. ### `@explain` @@ -49,6 +87,16 @@ The `@explain` command prefix within Navie serves as a default option focused on - @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? +### `@diagram` + +The `@diagram` command prefix within Navie focuses the AI response to generate Mermaid compatable diagrams. [Mermaid](https://mermaid.js.org/) is an open source diagramming and charting utility with wide support across tools such as GitHub, Atlassian, and more. Use the `@diagram` command, and Navie will create and render a Mermaid compatable diagram within the Navie chat window. You can open this diagram in the [Mermaid Live Editor](https://mermaid.live), copy the Mermaid Definitions to your clipboard, save to disk, or expand a full window view. Save the Mermaid diagram into any supported tool such as GitHub Issues, Atlassian Confluence, and more. + +#### Examples + +- @diagram how my user authentication works for the /admin API endpoint. +- @diagram the plan to implement a caching layer into my SQL database access. +- @diagram the relationship between the physical_flow, physical_specification, physical_spec_data_type data types. + ### `@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. @@ -59,18 +107,56 @@ Navie will help you setup AppMap, including generating AppMap recordings and dia - @help how can I reduce the size of my large AppMap Data recordings? - @help how can i export my AppMap data to atlassian confluence? +## Bring Your Own Model Examples + +### GitHub Copilot Language Model -### `@generate` +Starting with VS Code `1.91` and greater, and with an active GitHub Copilot subscription, you can use Navie with the Copilot Language Model as a supported backend model. This allows you to leverage the powerful runtime powered Navie AI Architect with your existing Copilot subscription. This is the recommended option for users in corporate environments where Copilot is the only approved and supported language model. -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. +#### Requirements -#### Examples +The following items are required to use the GitHub Copilot Language Model with Navie: -- @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 +- VS Code Version `1.91` or greater +- AppMap Extension version `v0.123.0` or greater +- GitHub Copilot VS Code extension must be installed +- Signed into an active paid or trial GitHub Copilot subscription -## Bring Your Own Model Examples +#### Setup + +Open the VS Code Settings, and search for `navie vscode` + + + +Click the box to use the `VS Code language model...` + +After clicking the box to enable the VS Code LM, you'll be instructed to reload your VS Code to enable these changes. + + + +After VS Code finishes reloading, open the AppMap extension. + +Select `New Navie Chat`, and confirm the model listed is `(via copilot)` + + + +You'll need to allow the AppMap extension access to the Copilot Language Models. After asking your first question to Navie, click `Allow` to the popup to allow the necessary access. + + + +#### Troubleshooting + +If you attempt to enable the Copilot language models without the Copilot Extension installed, you'll see the following error in your code editor. + + + +Click `Install Copilot` to complete the installation for language model support. + +If you have the Copilot extension installed, but have not signed in, you'll see the following notice. + + + +Click the `Sign in to GitHub` and login with an account that has a valid paid or trial GitHub Copilot subscription. ### OpenAI @@ -106,6 +192,21 @@ setting: Consult [AnyScale documentation](https://docs.endpoints.anyscale.com/) for model names. Note we recommend using Mixtral models with Navie. +### Fireworks AI + +You can use [Fireworks AI](https://fireworks.ai/) and their serverless or on-demand +models as a compatible backend for AppMap Navie AI. + +After creating an account on Fireworks AI you can configure your Navie environment +settings: + +| `OPENAI_API_KEY` | `WBYq2mKlK8I16ha21k233k2EwzGAJy3e0CLmtNZadJ6byfpu7c` | +| `OPENAI_BASE_URL` | `https://api.fireworks.ai/inference/v1` | +| `APPMAP_NAVIE_MODEL` | `accounts/fireworks/models/mixtral-8x22b-instruct` | + +Consult the [Fireworks AI documentation](https://fireworks.ai/models) for a full list of +the available models they currently support. + ### Ollama You can use [Ollama](https://ollama.com/) to run Navie with local models; after @@ -152,6 +253,8 @@ Continue to configure your local environment with the following environment vari **Note:** Even though it's running locally a dummy placeholder API key is still required. +{% include vimeo.html id='969002308' %} + ## OpenAI Key Management in VS Code ### Add a new OpenAI Key in VS Code diff --git a/docs/reference/uninstalling-appmap.md b/docs/reference/uninstalling-appmap.md index 21f24cd0ce..74f4f1bacd 100644 --- a/docs/reference/uninstalling-appmap.md +++ b/docs/reference/uninstalling-appmap.md @@ -11,15 +11,16 @@ 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-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) + - [Node.js](#nodejs) +- [Removing AppMap-generated files from your project](#removing-appmap-generated-files-from-your-project) +- [Removing Temporary AppMap Local Working Directories](#removing-temporary-appmap-local-working-directories) ## Uninstalling AppMap IDE Plugins @@ -51,7 +52,7 @@ Please note that even after uninstalling the IDE plugin, your project may still ## 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 +### Ruby Use the `bundle` command to remove the AppMap library from your project: {: .example-code} @@ -117,3 +118,12 @@ Finally, remove any generated AppMap files from your project: ```console $ rm -r tmp/appmap ``` + +## Removing Temporary AppMap Local Working Directories + +When installing the AppMap Extension for VS Code or JetBrains, AppMap will create a `$HOME/.appmap` folder +to store downloaded CLI binaries, jar files, local Navie chat history, and any other data necessary for +AppMap to operate. + +After you uninstall the AppMap extension for your code editor, you can safely delete the `$HOME/.appmap` directory +and all the data within. \ No newline at end of file diff --git a/docs/reference/vscode.md b/docs/reference/vscode.md index a01fe3b079..34172b57e3 100644 --- a/docs/reference/vscode.md +++ b/docs/reference/vscode.md @@ -18,6 +18,7 @@ step: 1 - ["Run with AppMap" for Java](#run-with-appmap-for-java) - [Extension actions](#extension-actions) - [Remote recording](#remote-recording) +- [Integration with GitHub Codespaces](#integration-with-github-codespaces) - [Generate OpenAPI Definitions](#generate-openapi-definitions) - [GitHub repository](#github-repository) @@ -52,7 +53,7 @@ All the HTTP server requests, SQL queries, packages, classes, and functions that ## "Run with AppMap" for Java -**NOTE:** This section only applies to Java applications. +
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. @@ -110,6 +111,14 @@ For more details about remote recording, see: * [Recording methods > Remote recording](../recording-methods#remote-recording) * [Remote recording API](../reference/remote-recording-api) +## Integration with GitHub Codespaces + +AppMap for VS Code supports GitHub Codespaces or other remote development environments. Currently AppMap only supports GitHub Codespaces natively in the VS Code Editor and not in the GitHub Web Based editor. + +Learn more about AppMap in GitHub Codespaces: + +{% include vimeo.html id='967812459' %} + ## 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/) diff --git a/docs/setup-appmap-in-ci/example-projects.md b/docs/setup-appmap-in-ci/example-projects.md deleted file mode 100644 index fa34c6747d..0000000000 --- a/docs/setup-appmap-in-ci/example-projects.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -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! diff --git a/docs/setup-appmap-in-ci/how-it-works.md b/docs/setup-appmap-in-ci/how-it-works.md deleted file mode 100644 index 42303f8bd5..0000000000 --- a/docs/setup-appmap-in-ci/how-it-works.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -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. - -

-Install the AppMap GitHub App on the GitHub Marketplace to get started now! -

- -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) diff --git a/docs/setup-appmap-in-ci/in-circleci.md b/docs/setup-appmap-in-ci/in-circleci.md deleted file mode 100644 index ce49dd04ed..0000000000 --- a/docs/setup-appmap-in-ci/in-circleci.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -layout: docs -title: Set up AppMap in CI -description: "Get started with AppMap and CircleCI for behavioral analysis in your test cases. Follow steps to sync files, set up GitHub Action, and analyze runtime code changes." -name: Getting Started with CircleCI -setup-appmap-ci: true -step: 3 -render_with_liquid: false ---- - -# Getting Started with CircleCI - -

-If at any point you would like some help, join us in Slack! -You'll find the AppMap team there, along with other AppMap users. -

- -- [How it works](#how-it-works) -- [Step-by-step walkthrough](#step-by-step-walkthrough) - - [Prerequisites](#prerequisites) - - [Step 1: Setup AppMap file sync in existing CircleCI Project](#step-1-setup-appmap-file-sync-in-existing-circleci-project) - - [Step 2: Setup AppMap GitHub Action for baseline](#step-2-setup-appmap-github-action-for-baseline) - - [Step 3: Add AppMap to compare HEAD revision](#step-3-add-appmap-to-compare-head-revision) - - [Step 4: Merge Pull Request to enable AppMap](#step-4-merge-pull-request-to-enable-appmap) -- [Example Project Files](#example-project-files) -- [Advanced Configuration Options](#advanced-configuration-options) - - [Prerequisites](#prerequisites-1) - - [Step 1: Add or Update AppMap action to use `repository_dispatch` trigger](#step-1-add-or-update-appmap-action-to-use-repository_dispatch-trigger) - - [Step 2: Update your CircleCI build to trigger the GitHub API on a successfully build completion.](#step-2-update-your-circleci-build-to-trigger-the-github-api-on-a-successfully-build-completion) -- [Next Steps](#next-steps) - -## Overview -AppMap works with your test cases in CircleCI and a GitHub Action to collect, store, analyze, and report on the behavioral changes within each Pull Request. Tests can execute within your existing CircleCI build job, and AppMaps can be retrieved by a GitHub Action to analyze the code behavior changes. - - - -## How it works - -AppMap records the behavior of your test cases when they run in CircleCI and produces AppMap data that can be copied to a centralized storage repository. An additional step is added in your CircleCI build job to create a tarball of that data and push the resulting file to a centralized object storage or file storage of your control. From there, the AppMap GitHub Action will download those maps and analyze them. AppMap will add comments to your Pull Request with deep insights into the runtime code changes. - - - -In this example, the following events will happen: - -1) CircleCI builds your application and runs automated test cases run with AppMaps created in `tmp/appmap` on the CircleCI runner. -- A tarball (`tar`) file of the `tmp/appmap` directory is created in the CircleCI runner. -- This tarball is copied to your chosen centralized location (such as AWS S3 or Azure Blob Storage) for secure storage and retrieval by the AppMap GitHub Action. - -2) While the CircleCI build is running, the AppMap GitHub Action will also trigger, looking for a baseline archive for comparison. - - The AppMap GitHub Action waits until all the AppMaps exist on the central storage location before continuing. - - This will download the raw AppMaps created by CircleCI in your previous step to generate a baseline archive for comparison. - -3) The GitHub Action will analyze the latest maps against the baseline for the pull request. - - The AppMap GitHub Action will provide a full runtime code analysis diff report as a comment in your pull request. - -## Step-by-step walkthrough - -### Prerequisites - -1) AppMap only supports project that have automated test cases. To add AppMap to your project, use either the [AppMap installer CLI](/docs/reference/appmap-client-cli.html#install) or manually add with the [AppMap libraries](/docs/reference). - -2) A centralized storage location (such as Amazon S3 or Azure Blob Storage) for storing raw AppMaps generated from the test cases. This storage needs write access from CircleCI and read access from GitHub Actions. In this example below we will use Amazon S3. - -### Step 1: Setup AppMap file sync in existing CircleCI Project - -First, create a branch called `appmap-ci` in your project. Next, in your CircleCI configuration (generally found at `.circle/config.yml`), add a run action that will create a (`tar`) of your AppMaps after your test cases are completed. - -```yaml -- run: - name: Create archive of AppMaps - command: tar --remove-files -cvzf <>.tar tmp/appmap/ -``` -{: .example-code} - -Using the CircleCI pipeline value of `<>` will give this archive tarball a unique file name based on the SHA the AppMaps are based on. - -After the archive step, add the necessary steps to authenticate and copy this archive file to your centralized storage location. In our example below, we will authenticate with Amazon AWS to generate temporary credentials and then we will copy this file to the configured bucket. In this example, copying the tarball to the `s3://circleci-appmaps/` bucket. - -```yaml -- aws-cli/setup: - profile_name: Circle-CI-Write-to-S3 - role_arn: arn:aws:iam::12345678900:role/Circle-CI-Write-to-S3 - -- aws-s3/copy: - from: <>.tar - profile_name: Circle-CI-Write-to-S3 - to: s3://circleci-appmap/ - arguments: --region us-west-2 -``` -{: .example-code} - -[**Example Code Commit**](https://github.com/land-of-apps/circle-ci-example/commit/1b1f2e886c8ca0a166296147b083d3eb500a8c5f) - -After you push this commit to your branch, CircleCI will trigger a workflow and you can confirm that the steps all completed successfully. - - - -Once you have confirmed your AppMaps have successfully copied to your centralized file repository, merge this branch and continue to the next step. - -### Step 2: Setup AppMap GitHub Action for baseline - -To setup the GitHub Action, create a new branch called `appmap-action` in your repository. - -Create a new file with the name `.github/workflows/appmap-analysis.yml` - -In this file you can use [this default action example](https://github.com/land-of-apps/rails-7-app/blob/c70b48891f38f92223ec06a654406cb7a6886890/.github/workflows/appmap-analysis.yml#L1-L77). **NOTE** Right now you will only use the first job that is listed in lines 1-77, after we create the baseline archive we'll add the AppMap job below this section. - -- Download the AppMap tooling into the runner. -- Check for an existing baseline AppMap archive stored in your GitHub artifact store. -- (If no baseline AppMap archive exists) Locate and download the tarball of AppMaps for the base revision from your chosen centralized data store. -- (If no baseline AppMap archive exists) Create an AppMap archive of the baseline AppMaps and store to your GitHub artifact store. - -Commit your GitHub Action workflow file to your branch and open a new Pull Request which will trigger the action. - -After the action completes running successfully, check the action summary and confirm a build artifact has been created like the following screenshot. - - - -### Step 3: Add AppMap to compare HEAD revision - -After the previous step succeeds and the baseline AppMap data is created, [update the GitHub Action](https://github.com/land-of-apps/rails-7-app/blob/c70b48891f38f92223ec06a654406cb7a6886890/.github/workflows/appmap-analysis.yml#L79-L125) to include a similar job to fetch the AppMaps for the HEAD revision and additionally analyze the code changes for code quality problems and provide a detailed report into the pull request comments. - -[Review this example commit](https://github.com/land-of-apps/circle-ci-example/pull/2/commits/4ea72bb9c930960dafd38698749a0b1dbc2e9db8) for an example of the additional steps to add to your GitHub Action. - -When the build completes successfully, you will see a comment from the GitHub Action. After merging this Pull Request you will see a similar analysis on each new Pull Request. - - - -Your completed installation should now look like the following [Pull Request Example.](https://github.com/land-of-apps/circle-ci-example/pull/2) - -### Step 4: Merge Pull Request to enable AppMap - -After you merge this Pull Request, AppMap will execute on each subsequent Pull Request. - -With AppMap deployed in your project, AppMap will execute on each Pull Request and provide a detailed runtime code analysis on each new commit. AppMap performs a thorough analysis of the runtime differences, giving you: - -- Root cause analysis of failed tests. -- Web service API changes, both breaking and non-breaking. -- 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. - -[Example Pull Request with Runtime Code Diff](https://github.com/land-of-apps/rails-7-app/pull/14) - - - - -## Example Project Files - -- [Example Ruby on Rails Project](https://github.com/land-of-apps/rails-7-app/) -- [Pull Request with Runtime Code Diff](https://github.com/land-of-apps/rails-7-app/pull/14) -- [CircleCI Example copying AppMaps to Amazon S3](https://github.com/land-of-apps/rails-7-app/blob/c70b48891f38f92223ec06a654406cb7a6886890/.circleci/config.yml#L34-L46) -- [GitHub Action Workflow File](https://github.com/land-of-apps/rails-7-app/blob/c70b48891f38f92223ec06a654406cb7a6886890/.github/workflows/appmap-analysis.yml) - -## Advanced Configuration Options - -In our basic CircleCI example above, both the CircleCI test runner and the AppMap action will start running at the same time. The GitHub Action will check your central storage location every 10 seconds until your baseline maps and HEAD revision maps exist. For many projects where your test cases can complete in a short amount of time, this additional wait time in the AppMap GitHub Action is worth the cost for the simpler configuration to get started. - -But if your test cases on CircleCi take longer to run, it can be inefficient and expensive to have a GitHub Action running and waiting for files to become available. You can use the GitHub API to trigger a webhook event called `repository_dispatch` when you want to trigger a workflow for activity that happens outside of GitHub. In our case after CircleCI has successfully finished running test and pushed the AppMap archive to the central file storage location. - -Refer to the [GitHub Action documentation](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#repository_dispatch) for more details about how the `repository_dispatch` action trigger works. - -The overall architecture largely stays the same as the basic example from above. You can see in the diagram below we've added a new step #2 where a CircleCI job will make a call to the GitHub API to trigger a webhook and start our updated GitHub Action. - - - -### Prerequisites - -- [Create a GitHub Personal Access Token](https://docs.github.com/en/enterprise-server@3.8/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with the `repo` scope. This needs to be stored in your CircleCI account as an environment variable. -- The `repository_dispatch` trigger will only run if your workflow file is on your main branch. As such, you'll need the ability to commit to your project main branch. -- Centralized storage setup and configured for access. As the example above, you'll need write access from CircleCI and read access from GitHub Actions. In our example we'll be using Amazon S3. -- This walkthrough assumes you have already completed the basic setup steps in the previous example. At the very least you need to ensure you've [completed Step 2](/docs/setup-appmap-in-ci/in-circleci.html#step-2-setup-appmap-github-action-for-baseline) and have a baseline AppMap archive ready for analysis. - -### Step 1: Add or Update AppMap action to use `repository_dispatch` trigger - -For this updated GitHub Action to work you'll need to commit a software utility to your project that will locate which Pull Request your commit is associated with. Normally when a Pull Request is opened, the AppMap Action will trigger and the action payload will include details about which Pull Request the AppMap report will be associated with. But since our action will be triggered via a webhook, it will lack information about what Pull Request is associated with the commit. - -#### Add `searchPullRequest.js` to your project - -You can use this JavaScript function to locate the Pull Request for your commits, and pass the relevant pull request number to the AppMap GitHub Action. [Copy the latest version from the sample project](https://github.com/land-of-apps/rails-7-app/blob/d098acdc0b3d327ebf8c9d062bedb5c779d18008/searchPullRequest.js) and add to your project. - -Add the following as a new file named `package.json` or add these project dependencies to your existing `package.json` - -```json -{ - "dependencies": { - "@octokit/rest": "^20.0.2", - "yargs": "^17.7.2" - } -} -``` -{: .example-code} - -#### Add/Update the AppMap Action to your project - -The most recent version of the AppMap GitHub Action that can be triggered via a [webhook is located in our sample project.](https://github.com/land-of-apps/rails-7-app/blob/cca7f276cf7c32b4b7a5af218ccf19399084777a/.github/workflows/analyze-maps-from-circleci.yml) You'll need to commit this file (configured for your environment) and the files above into the main branch of your repository. As with the above example you'll need to save this file into the `.github/workflows/` folder. - -**Commit these files to your main branch and then continue to Step 2.** - -This action has many steps to process the files and analyze your pull requests, below are details of what each step is doing. - -* Reconfigure this environment variable to point to your specific central file location. - -```yaml -env: - appmap_storage_bucket: circleci-appmaps -``` -{: .example-code} - -* Use this action to set the status of your Pull Request as "pending" for the commit being built. - -```yaml -- name: Set commit status as pending - uses: myrotvorets/set-commit-status-action@f8a3f50eca0d32f3e12dc3a98792bb588bf29626 - with: - token: ${{ secrets.GITHUB_TOKEN }} - status: pending - context: AppMap Analysis - sha: ${{ github.event.client_payload.head_sha }} -``` -{: .example-code} - - - - -* Install the AppMap command line tools, but do not install the libraries. - -```yaml - - name: Install AppMap tools - uses: getappmap/install-action@v1 - with: - install-appmap-library: false -``` -{: .example-code} - -* Check and see if the baseline AppMap archive exists in the GitHub artifact store. This will fail if an archive is not found so we enable `continue-on-error: true` - -```yaml -- name: Check for existing baseline archive - id: check_for_baseline - env: - GITHUB_TOKEN: ${{ github.token }} - continue-on-error: true - run: | - appmap restore --check --revision ${base_sha} --github-repo ${GITHUB_REPOSITORY} --exact -``` -{: .example-code} - -* If the previous step "fails" (i.e. no baseline archive exists) run these steps to download raw AppMaps and archive them for analysis. - -```yaml -- name: Download and extract appmaps - if: steps.check_for_baseline.outcome == 'failure' - run: | - aws s3 cp s3://${appmap_storage_bucket}/${base_sha}.tar ${base_sha}.tar - tar xvf ${base_sha}.tar - -- name: Archive AppMaps - if: steps.check_for_baseline.outcome == 'failure' - uses: getappmap/archive-action@v1 - with: - revision: ${base_sha} -``` -{: .example-code} - -The 2nd section in the GitHub AppMap Action will trigger when the above steps are successful. Below is an explanation of what each of those steps is used for. - -* As in the previous example, reconfigure the storage bucket location based on where your AppMaps are located. - -```yaml -env: - appmap_storage_bucket: circleci-appmaps -``` -{: .example-code} - -* Install Node.js and the packages required to run the `searchPullRequest.js` application. - -```yaml -- name: Use Node.js - uses: actions/setup-node@v2 - with: - node-version: '18' - -- name: Install dependencies - run: npm ci -``` -{: .example-code} - -* Download and extract the HEAD revision AppMaps sent from CircleCI - -```yaml -- name: Download and extract appmaps - run: | - aws s3 cp s3://${appmap_storage_bucket}/${head_sha}.tar ${head_sha}.tar - tar xvf ${head_sha}.tar -``` -{: .example-code} - -* Run `searchPullRequest.js` and locate the most recent Pull Request with the HEAD sha associated. This value will be stored in $LATESTPR. - -```yaml -- name: Get only the most recent issue with this head commit - run: echo LATESTPR=$(node searchPullRequest.js --ownerRepo=${GITHUB_REPOSITORY} --commit=${head_sha}) >> "$GITHUB_ENV" - -``` -{: .example-code} - -* Analyze the AppMaps and compare the changes between the base and head revisions, passing the `issue-number` to the analyze-action. - -```yaml -- name: Analyze AppMaps - uses: getappmap/analyze-action@v1 - with: - issue-number: ${{env.LATESTPR}} - directory: . - base-revision: ${{ github.event.client_payload.base_sha }} - head-revision: ${{ github.event.client_payload.head_sha }} -``` -{: .example-code} - -* Update the commit status for this repository_dispatch build. - -```yaml -- name: Update Commit Status - uses: myrotvorets/set-commit-status-action@v2.0.0 - if: always() - with: - token: ${{ secrets.GITHUB_TOKEN }} - status: ${{ job.status }} - context: AppMap Analysis - sha: ${{ github.event.client_payload.head_sha }} -``` -{: .example-code} - -The commit status update will look like the following in a sucessful pull request. - - - -Make sure to commit the [searchPullRequest.js](https://github.com/land-of-apps/rails-7-app/blob/d098acdc0b3d327ebf8c9d062bedb5c779d18008/searchPullRequest.js), the [package.json](https://github.com/land-of-apps/rails-7-app/blob/d098acdc0b3d327ebf8c9d062bedb5c779d18008/package.json), and the Webhook AppMap GitHub Action before continuing to step 2. - -[Here is an example commit with the changes files in an example test project.](https://github.com/land-of-apps/circle-ci-example/commit/44bcfafbaf978484fc0d29e826d28161ded89ef6) - -### Step 2: Update your CircleCI build to trigger the GitHub API on a successfully build completion. - -For an example of a full CircleCI workflow, [refer to the latest version from our sample project.](https://github.com/land-of-apps/rails-7-app/blob/235f97aa4225f4e6e43715b404182f1df7d5c6f5/.circleci/config.yml) - -In our example, we'll modify the CircleCI build runner from our basic example, and add a new build job called `run_appmap_analysis` which will only trigger on non-mainline code commits after the normal build succeeds. - -We don't need to trigger the Webhook based AppMap Action on a mainline branch build because analysis only happens inside of an existing Pull Request. - -First we can create a new job in our existing `.circleci/config.yml` file. - -You'll need to update the following items according to your project: - -- Ensure your GitHub Personal Access Token is saved as a CircleCI secure environment variable at `$GITHUB_PAT` -- Update the URL for triggering the `repository_dispatch` project. The format is: `https://api.github.com/repos/{ORGNAME}/{REPONAME}/dispatches` -- [Confirm the name of your `repository_dispatch`](https://github.com/land-of-apps/rails-7-app/blob/235f97aa4225f4e6e43715b404182f1df7d5c6f5/.github/workflows/analyze-maps-from-circleci.yml#L3-L7) action and update the `"event_type": "run_appmap_analysis",` accordingly. - -```yaml -run_appmap_analysis: - docker: - - image: cimg/ruby:3.1.2 - - steps: - - checkout - - - run: - name: Get base Git SHA - command: echo 'export BASE_SHA=$(git merge-base origin/main $CIRCLE_BRANCH)' >> $BASH_ENV - - - run: - name: Run AppMap Analysis - command: | - curl -L \ - -X POST \ - -H "Accept: application/vnd.github.v3+json" \ - -H "Authorization: token $GITHUB_PAT" \ - -H "Content-Type: application/json" \ - -H "X-GitHub-Api-Version: 2022-11-28" \ - https://api.github.com/repos/land-of-apps/rails-7-app/dispatches \ - -d @- \<>" - } - } - EOF -``` -{: .example-code} - -In your CircleCI workflow declaration section. Update the jobs so that the GitHub webhook job will only run after the build job and excluding your mainline branch. - -```yaml -workflows: - build: - jobs: - - build - - run_appmap_analysis: - requires: - - build - filters: - branches: - ignore: - - main -``` -{: .example-code} - -Now, create a new Pull Request with these changes and on your next CircleCI build, you'll see that the `run_appmap_analysis` job will execute after your normal build step. - - - -For more details refer to this [example Pull Request](https://github.com/land-of-apps/circle-ci-example/pull/3) and [commit changes](https://github.com/land-of-apps/circle-ci-example/pull/3/commits/8c328130e0572a0eee9b9a0e0b1b2d73e3909ebc) for this sample project. - -When you view your project's GitHub Actions page, you'll see the `workflow_dispatch` action trigger after CircleCI completes its build after it has uploaded the AppMaps to your centralized data store. - - - -## Next Steps - -AppMap comes with a comprehensive set of rules that are categorized by their impact on applications: Performance, Reliability, Maintainability, Stability, and Security. [Refer to the AppMap documentation](/docs/setup-appmap-in-ci/in-github-actions.html#configure-additional-appmap-analysis-rules) to learn how to configure these rules for your project. \ No newline at end of file diff --git a/docs/setup-appmap-in-ci/in-github-actions.md b/docs/setup-appmap-in-ci/in-github-actions.md deleted file mode 100644 index e337049205..0000000000 --- a/docs/setup-appmap-in-ci/in-github-actions.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -layout: docs -title: Set up AppMap in CI -description: "Learn how to leverage AppMap within GitHub Actions to analyze behavioral changes in Pull Requests. Install AppMap and configure rules for enhanced performance and security." -name: Getting Started with GitHub Actions -setup-appmap-ci: true -step: 2 -render_with_liquid: false -redirect_from: [/docs/early-access/in-github-actions,/docs/analysis/in-github-actions] ---- - -# Getting Started with GitHub Actions - -

-If at any point you would like some help, join us in Slack! -You'll find the AppMap team there, along with other AppMap users. -

- -

-Make sure to install the AppMap App from the GitHub Marketplace before you start the installation process. -

- -Install AppMap for GitHub Actions - -## Overview -AppMap can work within GitHub Actions 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, both breaking and non-breaking. -- 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. - - - -## Step-by-step walkthrough - - - [Step 1: Install the AppMap GitHub App from the GitHub Marketplace.](#step-1-install-the-appmap-github-app-from-the-github-marketplace) - - [Step 2: Choose an Installation Method](#step-2-choose-an-installation-method) - - [Step 3: Grant Access to your repositories.](#step-3-grant-access-to-your-repositories) - - [Step 4: Complete the Installation Process](#step-4-complete-the-installation-process) - - [Step 5: Merge this PR to deploy AppMap](#step-5-merge-this-pr-to-deploy-appmap) -- [Optional Post-Install Configuration](#optional-post-install-configuration) - - [Configure Additional AppMap analysis rules](#configure-additional-appmap-analysis-rules) - -Configuration of the AppMap GitHub Action happens inside a branch and can be easily tested in a Pull Request before merging any code changes to the mainline branch. This allows users to easily test AppMap in the environment before deploying across the repository. - -Follow the steps below for your project. If you need additional assistance contact AppMap at [support@appmap.io](mailto:support@appmap.io) or join us in our [Community Slack](https://appmap.io/slack) - -### Step 1: Install the AppMap GitHub App from the GitHub Marketplace. - -Click to install the AppMap GitHub Action - -Installing the AppMap GitHub App into your repository will allow the AppMap installer to properly detect your repositories for installation. Your data is your data, AppMap does not store your code or any AppMaps that are generated. For more details about AppMap security controls, review the [Security FAQ](https://appmap.io/security). - -### Step 2: Choose an Installation Method - -AppMap runs as a GitHub Action in your project. Add AppMap to a project with an existing GitHub workflow that runs tests successfully. Choose if you would like to install AppMap manually into your project or use the automated AI assisted installation. - - - -### Step 3: Grant Access to your repositories. -Granting AppMap access to your repositories allows AppMap to complete an automated installation for your project. For the automated installation to be successful you'll need an existing GitHub workflow which builds and tests your application successfully. - - - -*Note*: If you do not currently have a GitHub Action that can run your test cases, refer to the [GitHub documentation](https://docs.github.com/en/actions/quickstart) to build an Action that will execute your test cases. - -### Step 4: Complete the Installation Process - -Follow the steps in the AppMap installation process to complete the AppMap Installation. AppMap will add a Configuration Report as a comment in the initial pull request. - - - -The initial AppMap report will give you details about: - -- **AppMap data sources** shows how many AppMaps were recorded, and which test frameworks were used. -- **Code profile** indicates which packages and modules were recorded. -- **Web service API profile** summarizes the HTTP requests observed while your tests ran. AppMap uses this information to automatically generate OpenAPI definitions. -- **SQL profile** summarizes the SQL queries executed in your tests. - -After completing the initial configuration report, AppMap will analyze your entire source code repository. In this report AppMap will display recently introduced code flaws and problems. A sample of all the problems that were found in the AppMaps are listed in order of when they were most likely introduced, with most recent first. - - - -### Step 5: 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. - - To see AppMap in action, create a draft pull request with some changes that you don't plan to merge. Some suggested changes include: - -- Add a new test -- Add, change, or remove an API route -- Change how your application interacts with its database - -AppMap will execute runtime code analysis on every pull request in this repository. - -
- -
- -## Optional Post-Install Configuration - -### Configure Additional AppMap analysis rules - -AppMap comes with a comprehensive set of rules that are categorized by their impact on applications: Performance, Reliability, Maintainability, Stability, and Security. - -You can refer to the [AppMap Documentation](/docs/reference/analysis-rules) for more information about all the rules that are available within AppMap. - -To enable additional rules simply add them to an `appmap-scanner.yml` file in the root of your project directory and commit it to your project. - -This is a sample `appmap-scanner.yml` file which you can use to enable or disable certain AppMap analysis rules. Rules can be disabled by commenting them out with the `#` character. - -```yaml -checks: - - rule: authz-before-authn - # - rule: circular-dependency - - rule: deprecated-crypto-algorithm - - rule: deserialization-of-untrusted-data - - rule: exec-of-untrusted-command - - rule: http-500 - # - rule: illegal-package-dependency - # properties: - # callerPackages: - # - equal: actionpack - # calleePackage: - # equal: app/controllers - # - rule: incompatible-http-client-request - # - rule: insecure-compare - # - rule: job-not-cancelled - - rule: logout-without-session-reset - # - rule: missing-authentication - - rule: missing-content-type - - rule: n-plus-one-query - # - rule: query-from-invalid-package - # - rule: query-from-view - # - rule: rpc-without-circuit-breaker - # - rule: save-without-validation - - rule: secret-in-log - # - rule: slow-function-call - # properties: - # timeAllowed: 0.2 - # functions: - # - match: Controller#create$ - # - rule: slow-http-server-request - # properties: - # timeAllowed: 0.5 - # - rule: slow-query - # properties: - # timeAllowed: 0.05 - - rule: too-many-joins - - rule: too-many-updates - # - rule: unbatched-materialized-query - - rule: unauthenticated-encryption - - rule: update-in-get-request -``` -{: .example-code} - -Add these changes to Git and commit and put them into the PR branch. - -```bash -$ git add . -$ git commit -m "ci: Add customized scanner configuration" -``` -{: .example-code} - -Push the changes upstream to your branch which updates the Pull Request. -```bash -$ git push -``` -{: .example-code} - -The AppMap analysis report will be updated on the completion of the build and a new report will be displayed. - -For more details about AppMap GitHub Actions refer to the [reference documentation](/docs/reference/github-action) diff --git a/docs/setup-appmap-in-ci/index.md b/docs/setup-appmap-in-ci/index.md deleted file mode 100644 index f4ee6c43dc..0000000000 --- a/docs/setup-appmap-in-ci/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -layout: docs -title: Set up AppMap in CI -description: "Learn to set up AppMap in CI using GitHub Actions or CircleCI. Explore how it works, example projects, and troubleshooting tips." -redirect_from: [/docs/analysis/integrating-with-ci/] ---- - -# Set up AppMap in CI - -

-If at any point you would like some help, join us in Slack! -You'll find the AppMap team there, along with other AppMap users. -

- -Get Started with our GitHub integration - -- [How it works](/docs/setup-appmap-in-ci/how-it-works) -- [Getting Started with GitHub Actions](/docs/setup-appmap-in-ci/in-github-actions) -- [Getting Started with CircleCI](/docs/setup-appmap-in-ci/in-circleci) -- [Example Projects](/docs/setup-appmap-in-ci/example-projects) -- [Matrix Builds](/docs/setup-appmap-in-ci/matrix-builds) -- [Troubleshooting](/docs/setup-appmap-in-ci/troubleshooting) \ No newline at end of file diff --git a/docs/setup-appmap-in-ci/matrix-builds.md b/docs/setup-appmap-in-ci/matrix-builds.md deleted file mode 100644 index 12b1e2e135..0000000000 --- a/docs/setup-appmap-in-ci/matrix-builds.md +++ /dev/null @@ -1,225 +0,0 @@ ---- -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..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. - - - -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. - - - -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} - -

-See an example GitHub Action configuration with AppMap working with a multi-runner matrix build. -

- -### 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. \ No newline at end of file diff --git a/docs/setup-appmap-in-ci/troubleshooting.md b/docs/setup-appmap-in-ci/troubleshooting.md deleted file mode 100644 index cdd195231c..0000000000 --- a/docs/setup-appmap-in-ci/troubleshooting.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -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 - -- [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**. - - - -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@* -``` - - - -## 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`. - - - -2) Select the GitHub account in which you are using AppMap, and then click the `Install` button. - - - -3) Select `All Repositories`, or select to install the app into specific repositories. - - diff --git a/docs/setup-appmap-in-your-code-editor/add-appmap-to-your-code-editor.md b/docs/setup-appmap-in-your-code-editor/add-appmap-to-your-code-editor.md deleted file mode 100644 index 727ace0cdc..0000000000 --- a/docs/setup-appmap-in-your-code-editor/add-appmap-to-your-code-editor.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -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 Visual Studio Code Marketplace. - - - -1. Open extensions from the sidebar in Visual Studio Code -2. Type 'AppMap' into the search bar -3. Click to install - - - - Install from the VS Code Marketplace - - -### 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). - -
If you do not see an option to Activate AppMap, upgrade to the latest version of the AppMap extension.
- - - -## AppMap for JetBrains IDEs - -The AppMap plugin has official support for **IntelliJ**, **PyCharm**, and **RubyMine** listed on the JetBrains Marketplace. - - - -1. Start your JetBrains IDE and open Preferences -2. Open Plugins, then click on Marketplace -3. Search for AppMap, select and install AppMap - - - - Install from the JetBrains Marketplace - - -### 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). - -
If you do not see an option to Activate AppMap, upgrade to the latest version of the AppMap plugin.
- - - -## 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 - -

To get access to AppMap Navie you need to be running AppMap VS Code Plugin version >= 0.118.1

- -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) - - - -**NOTE**: Make sure to either reload the extension, or reload/restart VS Code after updating the plugin. - -### Update AppMap for JetBrains code editors - -

To get access to AppMap Navie you need to be running AppMap JetBrains Plugin version >= 0.64.0

- -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) - - - -**NOTE**: Make sure to either reload the extension, or reload/restart JetBrains after updating the plugin. diff --git a/docs/setup-appmap-in-your-code-editor/appmap-analysis.md b/docs/setup-appmap-in-your-code-editor/appmap-analysis.md deleted file mode 100644 index ec52d957ea..0000000000 --- a/docs/setup-appmap-in-your-code-editor/appmap-analysis.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -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 - - -#### JetBrains editors - - -### The **Runtime Analysis** sidebar pane - -In Visual Studio Code, findings are displayed In the Runtime Analysis sidebar pane sorted by impact category and type. - - - -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. - - - -{% 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. - - - -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. - - -## 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. - - -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. - - -**Next step: [Join the AppMap Community](/community)** diff --git a/docs/setup-appmap-in-your-code-editor/generate-appmap-data-from-tests.md b/docs/setup-appmap-in-your-code-editor/generate-appmap-data-from-tests.md deleted file mode 100644 index e4b09be0f8..0000000000 --- a/docs/setup-appmap-in-your-code-editor/generate-appmap-data-from-tests.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -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. - - - -## 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. - - - -## 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. - - - -## 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. - - diff --git a/docs/setup-appmap-in-your-code-editor/generate-appmap-data-with-remote-recording.md b/docs/setup-appmap-in-your-code-editor/generate-appmap-data-with-remote-recording.md deleted file mode 100644 index 6f7385d778..0000000000 --- a/docs/setup-appmap-in-your-code-editor/generate-appmap-data-with-remote-recording.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -layout: docs -title: Docs - AppMap in your Code Editor -description: "Generate AppMap Data through remote recording for detailed HTTP request sequences. Install AppMap agent and follow steps for remote recording in various languages." -name: Generate AppMap Data with Remote Recording -step: 4 -setup-appmap-ide: true -redirect_from: [/docs/your-first-15-minutes-with-appmap/generate-appmaps-with-remote-recording, /docs/setup-appmap-in-your-code-editor/generate-appmaps-with-remote-recording] ---- - -# Generate AppMap Data with Remote Recording - -Remote recording enables you to create an AppMap while interacting directly with your app through the UI or API. - -Some benefits of remote recording include: - -* **Named by you** When you finish creating a remote recording, you give it a name that makes sense to you. For example, you can name it for the user flow, or the ID number of the issue that you are trying to reproduce. -* **Contains a sequence of requests** A remote recording AppMap contains the entire sequence of HTTP server requests that occur as you use the application. -* **Contains both foreground and background work** A remote recording AppMap contains all threads of execution, not just the web server. So you can see background jobs, message queue activity, and other threads of activity along with the main HTTP server request. -* **Ideal for sharing** When you reproduce a bug, security vulnerability, or performance problem in a remote recording AppMap, you can share it with colleagues so they can see exactly what the problem is. An AppMap contains much more information than the source code itself. - -The steps for creating a remote recording are: - -1. Start your application server with remote recording enabled: - - * [Remote recording - Ruby](/docs/reference/appmap-ruby#remote-recording) - * [Remote recording - Python](/docs/reference/appmap-python#remote-recording) - * [Remote recording - Java (IntelliJ)](/docs/reference/jetbrains#running-a-java-application-with-appmap) - * [Remote recording - Java (VS Code)](/docs/reference/vscode#remote-recording) - * [Remote recording - Java (command line)](/docs/reference/appmap-java#remote-recording) - * [Remote recording - Node.js](/docs/reference/appmap-node#remote-recording) - -{% include vimeo.html id='916087968' %} - ---- - -**In this video** -We generate AppMap Data with a remote recording of our application. You can remote record your application if your app doesn’t have complete test cases, or when you want to dive into a specific user interaction such as an API call or specific product functionality in your app. - -**Links mentioned** -[Rails Sample Application](https://github.com/land-of-apps/sample_app_6th_ed/tree/codespaces-devcontainer) -[Early Access to AppMap Analysis](/appmap-analysis) -[Detailed Remote Recording instructions for Rails](/docs/reference/appmap-ruby.html#remote-recording) -[Detailed Remote Recording instructions for Java](/docs/reference/appmap-java.html#remote-recording) - ---- - -## Follow along - -In this tutorial we are going to generate AppMap Data with a remote recording of our application. You can remote record your application if your app doesn’t have complete test cases, or when you want to dive into a specific user interaction such as an API call or specific product functionality in your app. - -We are going to be using [a sample ruby on rails application](https://github.com/land-of-apps/sample_app_6th_ed/tree/codespaces-devcontainer), which is a basic Twitter clone. If you have followed the previous tutorials, you’ll have [AppMap installed, and have already generated AppMap Data for your test cases](/docs/setup-appmap-in-your-code-editor/generate-appmap-data-from-tests). - -## Install AppMap agent - -**NOTE:** If you're using JetBrains IntelliJ IDEA with Java, [follow these instructions](/docs/reference/jetbrains#remote-recording) to create AppMap Data using remote recording. - -We’re going to open the AppMap for Visual Studio Code extension and install the AppMap agent. Our installer will confirm that the project meets all the requirements necessary to create maps. - - - -We’ll run the AppMap installer, select `bundler`, since this is a Ruby on Rails project. - - - -You’ll see that the only changes thus far to our repository are the addition of an AppMap configuration file and the AppMap gem being added as a development dependency. - - - -## Recording AppMap Diagrams - -Next, follow the on-screen instructions for recording AppMap Data. You'll receive one of the two following options. - -First, you may be instructed to run your application as you normally would. In this scenario, AppMap will automatically be enabled and each web request will generate a new AppMap. - -If you see this screen, follow along with [request recording AppMap Data](/docs/setup-appmap-in-your-code-editor/generate-appmap-data-with-request-recording). - - - -Otherwise, you'll be given a command to copy and paste into the terminal which will guide you through running your application with AppMap enabled. - -`npx @appland/appmap record` - - - -Before I run that command, I’m going to want to start my application locally and make sure I can connect to it. I’m going to open another terminal window and run: - -`bundle exec rails server` - -If you are remote recording a Java application or other language, please refer to the [AppMap documentation](/docs/recording-methods.html) for the relevant tutorials for those languages. With my app now running you can see that I can login to my app, navigate around, post a tweet, see users. - -We’ll now return to our console and run the `record` command. If I omit passing any options, I’ll be prompted to choose how to record the app. I’ll choose remote recording. AppMap will try to locate your running application locally, if your app is running in a container or elsewhere you may get an error. Simply follow the instructions to walk through the available configuration options to connect to your service. - - - -## Interact with Application - -Now that the agent is connected, we can hit enter to begin recording. Now, I can interact with my application, kick off a specific functional or integration test, or make any specific API calls to your application. I’m going to login and reset my password. It’s important to keep remote recordings focused on a specific function, and not include too many interactions in one single AppMap Data recording as they can grow large as recordings progress. - -When I am done interacting, I return back to the terminal and hit enter again to stop the recording. We’ll give this recording a name and then this AppMap will be opened within VS Code. - - - -## Open AppMap Diagrams - -We’ll also receive a runtime analysis scan of this code path as well, which has identified a performance issue with an N+1 SQL query generating the main list of tweets. For early access to our AppMap runtime analysis [reach out to us](/appmap-analysis). - - - -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. But you can commit changes to your Gemfile and the appmap configuration file which will make the project available to other developers. - - diff --git a/docs/setup-appmap-in-your-code-editor/generate-appmap-data-with-request-recording.md b/docs/setup-appmap-in-your-code-editor/generate-appmap-data-with-request-recording.md deleted file mode 100644 index 74236efd2f..0000000000 --- a/docs/setup-appmap-in-your-code-editor/generate-appmap-data-with-request-recording.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -layout: docs -title: Docs - AppMap in your Code Editor -description: "Learn to use AppMap to configure your app to record AppMap Data of HTTP requests, easily sort and name them." -name: Generate AppMap Data with Request Recording -setup-appmap-ide: true -redirect_from: [/docs/your-first-15-minutes-with-appmap/streaming-appmaps-with-request-recording, /docs/setup-appmap-in-your-code-editor/generate-appmaps-with-request-recording] -step: 5 ---- - -# Generate AppMap Data with Request Recording - -You can configure your application to record an AppMap of each HTTP server request. - -Some characteristics of request recording include: - -* **Named for the route** The name of each AppMap contains the HTTP request method and path, so you can see at a glance what request AppMap contains. -* **Sortable by timestamp** In the AppMap extension, AppMap Data recorded from requests are sorted by timestamp, with newest AppMap Diagrams at the top. So you can see a chronology of the requests that your app is serving. - -For details on requests recording, see: - -- [Requests recording - Ruby](/docs/reference/appmap-ruby#requests-recording) -- [Requests recording - Python](/docs/reference/appmap-python#requests-recording) -- [Requests recording - Java](/docs/reference/appmap-java#requests-recording) - -{% include vimeo.html id='916048527' %} - ---- - -**In this video** -We enable automatic recording of a Ruby on Rails application and stream AppMap Data into VS Code for each request as we interact with our application. Now available for Ruby on Rails applications, you can generate AppMap Diagrams for each request automatically by simply running your application locally and interacting or making API requests. - -**Links mentioned** -[Requests Recording](/docs/recording-methods.html#requests-recording) -[Requests Recording in Rails](/docs/reference/appmap-ruby#requests-recording) -[Requests Recording in Python](/docs/reference/appmap-python#requests-recording) - ---- - -## Follow along - -In this tutorial we are going to show you the latest way to generate AppMap Diagrams for your application, streaming AppMap Data for each request. - -This feature is currently available for [Ruby on Rails](/docs/reference/appmap-ruby#requests-recording), as well as [Python](/docs/reference/appmap-python#requests-recording) applications that use Django or Flask. - -## Install AppMap agent - -You can add AppMap to your project now by simply clicking the automated installer. This automatically adds the AppMap libraries to your project and will run your projects’ package manager such as Bundler, Pip, Poetry, and others. - - - -You could also skip the automated installer and add this to the top of your Gemfile in this Rails example. - -``` -# This must be the first gem listed -gem 'appmap', group: %i[test development] -``` - -With AppMap installed in this project, we can now start recording. You can record AppMap Diagrams by running your test cases, or by starting a remote recording of a user interaction. But now you can simply just start your project and AppMap will automatically record every request as it happens. - -I will now start my rails application, this is our AppMap merch store based on the open source project Solidus. You will see AppMap is enabled by default for the development environment. - - - -I can now interact with my application and AppMap Data will start to stream into my code editor. We’ll highlight HTTP server requests, SQL Queries, and highlight important AppMap Diagrams. - -I can then open the AppMap Diagrams to see which packages and functions interact with my database for example. - -And of course, AppMap will be continually alerting on performance and security issues for this project with AppMap Analysis. - - - -With that we find an [authorization happening before authentication](/docs/reference/analysis-rules#authz-before-authn). This is the #1 security flaw on the OWASP Top Ten - and no other tool can detect it. - - - -Head over to [the Get AppMap page](/get-appmap) to get started with our VS Code or JetBrains extension and add AppMap to your project today. diff --git a/docs/setup-appmap-in-your-code-editor/how-appmap-works.md b/docs/setup-appmap-in-your-code-editor/how-appmap-works.md deleted file mode 100644 index eb5f6debfb..0000000000 --- a/docs/setup-appmap-in-your-code-editor/how-appmap-works.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -layout: docs -setup-appmap-ide: true -title: Docs - AppMap in your Code Editor -description: "Learn how AppMap works: recording agents for Java, Python, Ruby, and Node.js, configuration, recording methods, AppMap files, running in containers, and viewing AppMap Diagrams." -step: 1 -name: How AppMap Works -redirect_from: [/docs/your-first-15-minutes-with-appmap/what-is-appmap,/docs/your-first-15-minutes-with-appmap/ideal-projects,/docs/your-first-15-minutes-with-appmap/appmap-analysis,/docs/guides/how-appmap-works] ---- - -# How AppMap Works - -- [Language "agent"](#language-agent) -- [appmap.yml configuration](#appmapyml-configuration) -- [Recording methods](#recording-methods) -- [About AppMap files](#about-appmap-files) -- [Running in containers](#running-in-containers) -- [Viewing AppMap Diagrams](#viewing-appmap-diagrams) - -## Language “agent” - -The AppMap process begins with the AppMap recording agent. This “agent” is a language-specific library - agents are available for Java, Python, Ruby and Node.js (Beta). You add the agent as a dependency of your project in the normal manner - via Maven, Gradle, Pip, Bundler, Yarn, etc. Then you configure your application to load the agent when the application runs. - - - - - - - - - - - - - - - - - - - - - - - - - - - -
JavaPythonRubyNode.js
-javaagent JVM option Django environment test and/or development bundlenpx appmap-node yourapp
Gradle pluginFlask environment
Maven plugin
- - - -_Running application code with the AppMap agent enabled_ - -AppMap is designed to record and display the code internals of your project, along with important I/O operations. Here’s a comparison of AppMap with other runtime code tools: - - - - - - - - - - - - - - - - - - - - - - - - - - -
AppMap ProfilerException reporterDebuggerAPM / Telemetry
Primary focusYour code
Parameters and return values
I/O
Log statements
Execution stack
Timing data
Exceptions		All code (your code + dependencies)
Execution stack
Timing data		Exceptions
Execution stack 		All code
Parameters and return values
Execution stack
Exceptions		I/O
Log statements
Timing data
Your code (limited)
Environmentdevelopment, test, staging, CIdevelopment, staging staging, productiondevelopmentproduction
- - -To summarize, AppMap is designed primarily to record _full details of your code_, including _parameters and return values_, as well as _I/O_ (especially _SQL_ and _HTTP client requests_), it includes _log statements_, the _execution stack_, _timing information_, and _exceptions_. It captures all of this with minimal configuration. It’s designed primarily for non-production environments. - -## appmap.yml configuration -When you start your app with the AppMap agent enabled, it reads a configuration file called appmap.yml. This file serves several basic purposes. It tells the AppMap agent: - -* Which code to record -* Where to write the AppMap Data. - -And it also tells other AppMap tools: -* The project name -* The language name -* Where the AppMap Data is located - -**Note:** In most environments, a default appmap.yml will be auto-generated by the AppMap agent if none exists. - -### Specifying which code to record -To get started, you just provide the top-level package names or directories containing the code you want to record. For a non-compiled language like Ruby, Python, or Node.js, it’s a directory list like `[ app]` or `[ src, lib ]`. For Java, it’s a package prefix like `org.mycorp`. - -Going beyond this basic, initial configuration, you have fine-grained control over which code to record. You can choose to record selected dependency libraries or packages. You can also include or exclude specific packages, classes and/or functions. And you can apply custom “labels” to any function, in order to organize the code into functional groups and to facilitate reasoning and analysis. - -## Recording methods -The AppMap agent can be enabled in any environment, and configured to record selected code. There are several variants of this basic model that are commonly used to acquire AppMap Data for specific use cases. - -### Test case recording -AppMap provides specialized support for recording test cases. When you run your test cases in a supported framework (there are many - see the [language agent reference](/docs/reference) for details), a separate AppMap Diagram is created for each test case. AppMap Diagrams created from tests cases have some distinct features: - -* Each AppMap file is named for the test case, and stored in a folder called `$appmap_dir/$test_framework` -* The test framework name and version are stored in the AppMap. -* The test case name, file name and line number are stored in the AppMap. -* The test status (`succeeded` or `failed`) and any test failure message are stored in the AppMap. - -Recording the test suite of an application is a good way to quickly obtain a lot of data about an application. And because test cases work the same way for each build, recording test cases is also a good way to compare the behavior of application code across versions. - -### Requests recording -For web applications, AppMap can be configured to record an AppMap for each HTTP server request handled by the app. This is a great way to collect data interactively. Just start the application with the AppMap language agent enabled, and start interacting with the app - manually, or using QA scripts or an API testing tool like Postman. AppMap Data is generated continuously as the application handles requests. - -### Remote recording -Remote recording is similar to requests recording, in that: -* It’s for web applications -* It makes AppMap Data as the application handles requests - -But unlike requests recording, you control the boundaries of the AppMap, each AppMap can contain more than one HTTP server request, and it will also contain non-HTTP activity such as background jobs. To start a remote recording, you send an HTTP command to the AppMap agent running inside your application’s web stack to start recording. From that point on, everything that happens inside the application is recorded, until you send the “stop” command. - -### Code block recording -Some language agents enable you to make an AppMap by adding a simple code snippet to your code. This gives you total control over what’s recorded. The only downside of this is that you need access to the source code - which is not required by other recording methods. - -### Process recording -Process recording is something of a last resort, when other recording methods aren’t available. When you run your application with process recording enabled, _everything_ that happens in the code (as configured by the appmap.yml) is recorded, from process startup to shutdown. - -## About AppMap files -AppMap Data is ordinary JSON files. As you record AppMap Data with test case recording, requests recording, or process recording, these JSON files are generated and written to the filesystem. The default location for AppMap Data is `tmp/appmap`, relative to the process working directory. Be sure that you know that the working directory of the application server is! You’ll need to know this to find and open your AppMap Diagrams. - -When you use remote recording, the HTTP “stop” command responds with the AppMap in the response payload. It’s up to the client to decide where to write the file. For example, you can start and stop a remote recording using cURL, and write the output of the “stop” command to a file of your choosing. - -When you use code block recording, it’s up to you in your code snippet to write the AppMap to a file. Naturally, you can direct the data anywhere you please. - -AppMap files conform to the [AppMap specification](https://github.com/getappmap/appmap), which is freely available on GitHub. - -## Running in containers -You can make AppMap Data while running your application in a container. From the AppMap standpoint, there is really no difference between running in a container and running in any other environment. There are just a couple of basic considerations: -* The AppMap file will be written to the filesystem of the container. To make it available to the host, you should either use a volume mount to the `$appmap_dir` (typically, `tmp/appmap`), or copy the AppMap Data out of the container after the recording is complete. -* If you are using remote recording, your application web port should be exposed to the host, so that you can send the HTTP start and stop commands. You’ll need this anyway, in order to access your application’s web UI or API from the host. - -## Viewing AppMap Diagrams -AppMap includes open-source UI tools to display AppMap Data as visual diagrams. Built-in diagrams include: - -* Dependency map -* Sequence diagram -* Trace view -* Flame graph - -These diagrams are integrated together in the AppMap UI, and fully interactive. The data can be organized, selected, and filtered by the user. This makes the user interface much better suited for code investigation than a static diagram image. It’s also much more scalable, because the diagrams can be tuned to reveal specific information and hide extraneous data. - -### IDE extensions -The AppMap extensions for VSCode and JetBrains include a file association for AppMap Data. Just click on an AppMap file, and it will be opened graphically in the code editor. The diagram is fully linked to source code within the IDE. - -### Hosting an AppMap viewer -The AppMap Diagrams are published as an open source library on [NPM](https://www.npmjs.com/package/@appland/appmap). If you want to provide a centralized service to open AppMap Diagrams in the browser, you can just serve [appmap.html](https://www.npmjs.com/package/@appland/appmap?activeTab=code) from any web server. Provide a URL to the AppMap Data using the `appmap` parameter - for example: `http://myappmapserver/appmap.html?appmap=https://`. - -### Exporting AppMap Data -The AppMap sequence diagram can be exported to SVG or PlantUML. Consult the [diagrams reference](/docs/guides/using-appmap-diagrams.html#sequence-diagram) for details. diff --git a/docs/setup-appmap-in-your-code-editor/index.md b/docs/setup-appmap-in-your-code-editor/index.md deleted file mode 100644 index 2f342dfb62..0000000000 --- a/docs/setup-appmap-in-your-code-editor/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -layout: docs -title: Docs - AppMap in your Code Editor -description: "Learn to set up and navigate AppMap in your code editor efficiently. Explore features like generating AppMap Data from tests and remote recording." -toc: true -redirect_from: [/docs/your-first-15-minutes-with-appmap/, /docs/code-editor-extensions/,/docs/code-editor-extensions/appmap-for-vs-code, /docs/code-editor-extensions/appmap-for-jetbrains] ---- - - -# Set Up AppMap in your Code Editor - -

-If at any point you would like some help, join us in Slack! -You'll find the AppMap team there, along with other AppMap users. -

- -* [How AppMap Works](/docs/setup-appmap-in-your-code-editor/how-appmap-works) -* [Add AppMap to your Code Editor](/docs/setup-appmap-in-your-code-editor/add-appmap-to-your-code-editor) -* [Generate AppMap Data from Tests](/docs/setup-appmap-in-your-code-editor/generate-appmap-data-from-tests) -* [Generate AppMap Data with Remote Recording](/docs/setup-appmap-in-your-code-editor/generate-appmap-data-with-remote-recording) -* [Generate AppMap Data with Request Recording](/docs/setup-appmap-in-your-code-editor/generate-appmap-data-with-request-recording) -* [Navigating AppMap Diagrams](/docs/setup-appmap-in-your-code-editor/navigating-appmap-diagrams) -* [Navigating Code Objects](/docs/setup-appmap-in-your-code-editor/navigating-code-objects) -* [Runtime Analysis](/docs/setup-appmap-in-your-code-editor/appmap-analysis) -* [Runtime Analysis](/docs/setup-appmap-in-your-code-editor/appmap-analysis) \ No newline at end of file diff --git a/docs/setup-appmap-in-your-code-editor/navigating-appmap-diagrams.md b/docs/setup-appmap-in-your-code-editor/navigating-appmap-diagrams.md deleted file mode 100644 index 4da494fdee..0000000000 --- a/docs/setup-appmap-in-your-code-editor/navigating-appmap-diagrams.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -layout: docs -title: Docs - AppMap in your Code Editor -description: "Learn to navigate AppMap Diagrams effectively. Discover Dependency and Trace views to enhance code understanding and execution analysis." -name: Navigating AppMap Diagrams -setup-appmap-ide: true -step: 6 -redirect_from: [/docs/your-first-15-minutes-with-appmap/navigating-appmaps, /docs/setup-appmap-in-your-code-editor/navigating-appmaps] ---- - -# Navigating AppMap Diagrams - -{% include vimeo.html id='916048549' %} - ---- - -**In this video** -We walk through how to navigate your AppMap Diagrams. We'll dive into the various sections of the AppMap view, such as the dependency view and the trace view. And we'll show you how to better understand your code execution by traversing your AppMap and how to link back to your code - -**Links mentioned** -[Rails Sample Application](https://github.com/land-of-apps/sample_app_6th_ed/tree/codespaces-devcontainer) -[Appland VS Code and JetBrains Extension](https://appmap.io/get-appmap) - ---- - -## Follow along - -Welcome to AppMap. If you’ve been following along this tutorial, you should have AppMap Diagrams generated from either your [test cases](/docs/setup-appmap-in-your-code-editor/generate-appmap-data-from-tests.html) or from a [remote recording](/docs/setup-appmap-in-your-code-editor/generate-appmap-data-with-remote-recording.html). This tutorial assumes you have at least one AppMap created, but ideally more than one. As always you can clone this [sample project repository from Github](https://github.com/land-of-apps/sample_app_6th_ed/tree/codespaces-devcontainer) and follow along. - -In this tutorial, we are going to dive into our AppMap Diagrams, show you how to navigate them and how to connect an AppMap back to your code. - -We’ll start by opening the AppMap extension installed in our VS Code editor. You’ll see a listing of all your AppMap Diagrams in your left hand column. From here, we can select on an AppMap to open it. - - - -There are 3 main sections to an AppMap. The left hand column will show you HTTP requests, labels, either automatically generated by AppMap or manually extended via simple code comments within your code base, a list of all the packages, classes, functions, and SQL queries associated with this AppMap. - -You can search across all of these code objects within this AppMap in the search bar and you can click the link to open the test case that generated this AppMap. - -## Dependency View - -In the right hand section, you’ll see the Dependency view which shows a visual representation between the code objects, functions, and SQL queries. Click on the “information” icon to see a full legend for the code objects and data values. - - - -In the top section, you’ll see a filter icon, click on this icon to help you declutter and focus your AppMap, which is particularly useful for larger and more complex maps. You can hide any unlabeled function, or hide specific packages, classes, or functions. For example, if I wanted to hide all of my logging functions from this AppMap, I can simply search for the `package:logger` and hide this from my view. - - - - -## Trace View - -If we click on one of the classes, such as `LoggedInHelper`, and select on the function, we can click on the event and go to the trace view of this AppMap. - -The trace view shows a hierarchical tree structure of what happened within that particular web request. If I keep clicking on `caller` i will get to the root which is the http server request. I can see the controller and the return status. - - - -I can see the values of the variables, parameters, and return values as the code traversed this test case. diff --git a/docs/setup-appmap-in-your-code-editor/navigating-code-objects.md b/docs/setup-appmap-in-your-code-editor/navigating-code-objects.md deleted file mode 100644 index 9fb82408c5..0000000000 --- a/docs/setup-appmap-in-your-code-editor/navigating-code-objects.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -layout: docs -title: Docs - AppMap in your Code Editor -description: "Explore AppMap's Code Objects view to navigate code functions, HTTP requests, and SQL queries across all AppMap Diagrams." -name: Navigating Code Objects -setup-appmap-ide: true -step: 7 -redirect_from: [/docs/your-first-15-minutes-with-appmap/navigating-code-objects] ---- - -# Navigating Code Objects -{% include vimeo.html id='916048582' %} - ---- - -**In this video** -Dive into the Code objects view, a high level view of code functions, HTTP requests, and SQL queries across the entire set of your AppMap Diagrams and learn how to locate and navigate to an AppMap from code reference pins on your code functions. - -**Links mentioned** -[Rails Sample Application](https://github.com/land-of-apps/sample_app_6th_ed/tree/codespaces-devcontainer) - ---- -## Follow along - -Welcome to AppMap, In this tutorial we will be diving into advanced navigation of AppMap Diagrams - the Code Objects view. We’ll answer the question, “What if I have a lot of AppMap Diagrams and I don’t know where exactly to look?” - -In this view, we collect all the different code functions and HTTP server requests and SQL queries all into one list. Every request, query, and function call that occurs anywhere in the whole set of AppMap Diagrams will be in this list. - -## Code Objects View - -There are three sections to the Code Objects view. The first section is the Code view, this will show packages, classes, and functions, it will show the framework code as well as my code, essentially everything present within your AppMap Diagrams. We can click on a function to navigate directly to the code. In this example, I’ll navigate to my Application controllers, and view the Microposts controller. This will take me directly to the code for this function. This is a great way to see more comprehensively what you have across your code base. - - - -## HTTP Routes List - -In the HTTP Service request list, you can see basically a mini spec file showing you what routes are available across all of your AppMap Diagrams. - -If this route only exists in a single AppMap, you’ll be taken directly to the AppMap for this request, but if the route exists in multiple diagrams you’ll get a VScode picker to choose which one to open. - -Here is this route, and here it is shown in a trace view, and you’ll see the status code for that is 302 which is a redirect. - - - -## SQL Query List - -The final section of Code Objects is a list of all the SQL queries across your AppMap Diagrams. Just like before, if you click into it and it is unique across your AppMap set then you’ll be sent directly to the AppMap or the quick picker will prompt you to open one. - -The code view is a handy way to navigate your code base, similar to the file view you’d get in VS Code except this code view will only show the code that participated in your test case recordings or remote recordings. - -But it’s more common to simply be navigating within the code itself. So what if you want to get to the AppMap Diagram from within the code? - -## Opening AppMap Diagrams from code object names - -The command “Open code object in AppMap” can be used to find and open all the AppMap Diagrams that contain a particular code object (package, class, or function name). - - - -To get here in VS Code open the command palette. - -On Mac: -`Shift + Command + P` - -On Windows/Linux: -`Ctrl + Shift + P` - -I can then search for the `UsersController#show` function - if it's in a single AppMap I’ll get taken directly to that AppMap. If it exists in more than one you’ll get the quick picker to choose which one you want.