@appland/appmap 3.146.0 → 3.147.0

package/built/docs/guides/runtime-code-review.md

@@ -0,0 +1,111 @@
+---
+layout: docs
+title: Docs - Guides
+description: "AppMap analyzes runtime changes in your codebase for failed tests, API, security, performance issues, and anti-patterns, providing detailed reports."
+guides: true
+name: Understanding the Runtime Code Review Report
+step: 10
+---
+
+# Understanding the Runtime Code Review Report <!-- omit in toc -->
+
+AppMap Analysis works with your Continuous Integration (CI) system to collect, store, analyze, and report on the behavioral changes within each Pull Request. AppMap analyzes 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 vulnerabilities.
+- New and resolved performance issues.
+- New and resolved flaws in other categories - maintainability, reliability, and user-defined rules.
+- Code Behavior diffs represented as sequence diagrams showing changed runtime behavior within the PR.
+
+<img class="video-screenshot" src="/assets/img/docs/guides/runtime-code-review.webp"/> 
+
+- [The AppMap Change Report](#the-appmap-change-report)
+- [Summary and Status](#summary-and-status)
+  - [Failed Tests](#failed-tests)
+  - [API Changes](#api-changes)
+  - [Security Flaws](#security-flaws)
+  - [Performance Problems](#performance-problems)
+  - [Code Anti-Patterns](#code-anti-patterns)
+  - [New AppMap Diagrams](#new-appmap-diagrams)
+
+## The AppMap Change Report
+
+Once a Pull Request is opened, reopened, or changed, an AppMap Analysis command will run to build a comparison report between the head revision and the most recent base revision for which an AppMap archive is available.  This ensures AppMap is only analyzing the code which changed in the pull request. This report compares structural differences observed at runtime between the feature and the origin point of that feature branch. The same action can also add comments and annotations to the source code changes involved in the Pull Request. The report data is also available as a JSON file.
+
+Key insights include:
+
+- How the new code will impact the system.
+- Any major architectural changes introduced.
+- Changes to the code interactions from API to Database
+
+Here is an example of a report from AppMap in CI:
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/analysis-github-action.webp"/>
+
+This report shows the runtime analysis done by AppMap, which records code execution behavior *before* those changes are approved for deployment to production.
+
+<img class="video-screenshot" src="/assets/img/docs/appmap_CI_report_top.webp"/> 
+
+## Summary and Status
+
+The summary gives you an overview of the following code-related flaws, problems, and anti-patterns. 
+
+- [The AppMap Change Report](#the-appmap-change-report)
+- [Summary and Status](#summary-and-status)
+  - [Failed Tests](#failed-tests)
+  - [API Changes](#api-changes)
+  - [Security Flaws](#security-flaws)
+  - [Performance Problems](#performance-problems)
+  - [Code Anti-Patterns](#code-anti-patterns)
+  - [New AppMap Diagrams](#new-appmap-diagrams)
+
+
+### Failed Tests
+
+AppMap will report on any tests that failed as part of your test suite. For each test that failed to complete successfully, AppMap will analyze the failed test, showing the full details of the error and the specific part of the test that failed. 
+
+<img class="video-screenshot" src="/assets/img/docs/appmap_CI_report_failed_tests.webp"/> 
+
+### API Changes
+
+AppMap will report on any changes seen with your API routes at runtime. AppMap will identify changes to routes themselves, notifying you when a new route appears or an existing route is deleted. Additionally, it will identify changes to the response body, content, descriptions, and other attributes.
+
+<img class="video-screenshot" src="/assets/img/docs/appmap_CI_report_api_changes.webp"/> 
+
+### Security Flaws
+
+AppMap analyzes your application's behavior to identify new security flaws in how the new code changes execute.  AppMap can identify issues such as:
+
+- [Deprecated cryptography algorithm](/docs/reference/analysis-rules.html#deprecated-crypto-algorithm)
+- [Logout without Session Reset](/docs/reference/analysis-rules.html#logout-without-session-reset)
+- [Deserialization of untrusted data](/docs/reference/analysis-rules.html#deserialization-of-untrusted-data)
+- and others.
+
+For a full list of all the flaws and issues which AppMap can detect, refer to the [Analysis Rules](/docs/reference/analysis-rules) reference section.
+
+### Performance Problems
+
+AppMap analyzes software behavior changes in your code base to identify performance problems before you merge your code changes. AppMap identifies a variety of software performance problems such as:
+
+- [N Plus One SQL Query](/docs/reference/analysis-rules.html#n-plus-one-query)
+- [Slow Function Calls](/docs/reference/analysis-rules.html#slow-function-call)
+- [Slow HTTP Server Requests](/docs/reference/analysis-rules.html#slow-http-server-request)
+- and others. 
+
+For a full list of all the flaws and issues which AppMap can detect, refer to the [Analysis Rules](/docs/reference/analysis-rules) reference section.
+
+### Code Anti-Patterns
+
+AppMap can identify any major or potential structural flaws in the architecture, or logical flow that could be introduced due to merging the feature into your application. Some examples of these code anti-patterns that AppMap can identify are: 
+
+- [Circular Dependencies](/docs/reference/analysis-rules.html#circular-dependency)
+- [Too Many SQL or RPC Updates](/docs/reference/analysis-rules.html#too-many-updates)
+- [SQL Queries from View Layer](/docs/reference/analysis-rules.html#query-from-view)
+- and others. 
+
+For a full list of all the flaws and issues which AppMap can detect, refer to the [Analysis Rules](/docs/reference/analysis-rules) reference section.
+
+### New AppMap Diagrams
+
+New test cases added to a pull request will lead to new AppMap Diagrams being created, with one AppMap created for each new test. AppMap will list all of the new diagrams (and therefore, each new test) created in each pull request. 

package/built/docs/guides/using-appmap-analysis.md

@@ -0,0 +1,206 @@
+---
+layout: docs
+title: Docs - Guides
+description: "Configure AppMap Analysis by customizing checks for flexible rule options. Understand findings and their properties for effective analysis."
+guides: true
+name: Using AppMap Analysis
+step: 8
+redirect_from: [/docs/analysis/configuring-checks, /docs/analysis/match-pattern-config, /docs/analysis/findings,/docs/reference/configuring-analysis,/docs/guides/configuring-analysis, /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](#navigate-findings)
+- [Investigate findings](#investigate-findings)
+- [Use labels to visually explore your code](#use-labels-to-visually-explore-your-code)
+- [Configuring Analysis](#configuring-analysis)
+- [Configuring checks](#configuring-checks)
+  - [Example appmap-scanner.yml](#example-appmap-scanneryml)
+- [Match pattern config](#match-pattern-config)
+  - [Examples](#examples)
+- [Findings Reference](#findings-reference)
+  - [Properties](#properties)
+  - [Finding hash](#finding-hash)
+
+## Navigate Findings
+
+Findings are displayed In the Runtime Analysis sidebar pane sorted by impact category and type.
+
+<image class="video-screenshot" src="/assets/img/docs/runtime-analysis-sidebar-findings.webp"/> 
+
+Clicking the ‘Overview’ link in the Runtime Analysis sidebar will open the ‘Runtime Analysis Summary’ window which contains a summary of findings for a particular project.
+
+<image class="video-screenshot" src="/assets/img/docs/runtime-analysis-overview-dashboard.webp"/> 
+
+{% include vimeo.html id='916087872' %}
+
+---
+
+**In this video**  
+AppMap Analysis scans your AppMap Data to find software design flaws that impact performance, stability, security and maintainability. This runtime code analysis can find the problems that static code analyzers miss - and that cause 90% of today’s most serious production issues.
+
+**Links mentioned**  
+[AppMap Community Slack](/slack)  
+[Get AppMap for VSCode](https://marketplace.visualstudio.com/items?itemName=appland.appmap)  
+[Get AppMap for JetBrains](https://plugins.jetbrains.com/plugin/16701-appmap)
+
+---
+
+## Investigate findings
+
+Let's look at a sample Ruby on rails application, where AppMap has already been installed and AppMap Data has been generated. From the test cases, you'll see a new option for findings in the left-hand column or an option here for investigate findings.
+
+<img class="video-screenshot" src="/assets/img/appmap-analysis-1.webp"/>
+
+You can see one of the issues we've found is that a log event contained secret data by clicking on the finding will be taken directly to the line of code where this event occurs by hovering over the pin.
+<img class="video-screenshot" src="/assets/img/appmap-analysis-2.webp"/>
+
+## Use labels to visually explore your code
+
+You can open the AppMap and see exactly where the function wrote this secret to a log file. How does AppMap know that this was a secret? Unlike static analyzers and other tools that do pattern matching AppMap knows this function generates secrets because we have built in knowledge of common software libraries with pre-populated labels.
+
+We know exactly where to look to avoid false positives. Developers can extend their labels, whether it's a common library or not with simple code comments on their functions.
+<img class="video-screenshot" src="/assets/img/appmap-analysis-3.webp"/>
+
+If you search for the secret label, you'll see the location in the code where this event occurs by clicking on the function, you'll be taken to the exact location of the AppMap, where the secret was generated. Additionally, you can open the code, combining a visual model alongside the code.
+<img class="video-screenshot" src="/assets/img/appmap-analysis-4.webp"/>
+
+## Configuring Analysis Checks
+
+AppMap Analysis is configured in a YAML document. It's primary job is to specify which scanner rules will check the code.
+Each check specifies a rule id, and may include additional properties that customized and tune the behavior of the rule.
+
+AppMap Analysis ships with a default configuration file located in `node_modules/@appland/scanner/built/sampleConfig/default.yml`.  
+
+Without specifying the `--config` command line option, AppMap will attempt to load `appmap-scanner.yml`, the default configuration for analysis rules. If that file does not exist, AppMap will fail back to loading the configuration in the `node_modules` path. 
+
+To use a non-default configuration, specify the path to the configuration file via the `-c` or `--config` option:
+
+```sh
+$ npx @appland/scanner \
+    --appmap-dir tmp/appmap \
+    --config appmap-scanner.yml \
+    ci
+```
+{: .example-code}
+
+To use a custom configuration create a file named `appmap-scanner.yml` in the root of your project directory, you can copy the [default.yml](https://github.com/getappmap/appmap-js/blob/main/packages/scanner/src/sampleConfig/default.yml) in the AppMap source code as a starting point.  Refer to the [Rules Reference](/docs/reference/analysis-rules) for additional configuration options per scanner rule. 
+
+### Example appmap-scanner.yml
+
+```
+checks:
+  - rule: authzBeforeAuthn
+  - rule: http500
+  - rule: illegalPackageDependency
+    properties:
+      callerPackages:
+        - equal: actionpack
+      calleePackage:
+        equal: app/controllers
+  - rule: insecureCompare
+  - rule: missingAuthentication
+  - rule: missingContentType
+  - rule: nPlusOneQuery
+  - rule: secretInLog
+  - rule: slowFunctionCall
+    properties:
+      timeAllowed: 0.2
+      functions:
+        - match: Controller#create$
+  - rule: slowHttpServerRequest
+    properties:
+      timeAllowed: 0.5
+  - rule: slowQuery
+    properties:
+      timeAllowed: 0.05
+  - rule: tooManyJoins
+  - rule: tooManyUpdates
+  - rule: unbatchedMaterializedQuery
+  - rule: updateInGetRequest
+```
+
+## Match pattern config
+
+Some rule options are defined as type `MatchPatternConfig`. `MatchPatternConfig` is a flexible way to
+match a string such as content type, code object name, etc.
+
+Each `MatchPatternConfig` requires one of the following three YAML keys:
+
+```yaml
+- match: RegExp   # String value must match this regexp
+- include: string # String value must include this substring
+- equal: string   # String value must equal this string
+```
+{: .example-code}
+
+Optionally:
+
+```yaml
+- ignoreCase: boolean # When true, the match/include/equal test is case-insensitive
+```
+{: .example-code}
+
+### Examples
+
+The `illegalPackageDependency` rule is applied to the package `app/controllers` (exactly). The caller package must
+be `actionpack` (exactly).
+
+```
+  - rule: illegalPackageDependency
+    properties:
+      callerPackages:
+        - equal: actionpack
+      calleePackage:
+        equal: app/controllers
+```
+
+The `slowFunctionCall` rule is applied to all functions that match one of two regular expressions (case sensitive).
+
+```
+  - rule: slowFunctionCall
+    properties:
+      functions:
+        - match: ^app/models
+        - match: ^app/jobs
+```
+
+The `missingAuthentication` rule is *not applied* to any event whose `route` includes `/api/`.
+
+```
+  - rule: missingAuthentication
+    exclude:
+      - event:
+          property: route
+          test:
+            include: /api/
+```
+
+## Findings Reference
+
+When a scanner check matches an AppMap, it issues a _finding_.  A finding includes detailed information about the match, indicating such information as:
+
+* A title and message.
+* AppMap in which the finding was found.
+* The primary and secondary events that are relevant to the finding.
+
+### Properties
+
+* `ruleId` identifier of the [rule](/docs/reference/analysis-rules) algorithm.
+* `checkId` identifier of the `check`, which a configured instance of a `rule`.
+* `ruleTitle` human-friendly title of the rule.
+* `message` human-friendly message describing the finding.
+* `appMapFile` relative path to the [AppMap](https://github.com/getappmap/appmap#appmap-data-specification) file containing the match.
+* `event` JSON object of the primary [event](https://github.com/getappmap/appmap#events) on which the match was found.
+* `relatedEvents` JSON of other events in the AppMap which are associated with the finding. They can be inspected in the AppMap to better understand the finding.
+* `scope` JSON of the event which defines the AppMap subtree in which the finding was discovered. 
+* [`hash`](#finding-hash) of the finding which can be used to identify duplicate findings.
+
+### Finding hash
+
+A `hash` of the finding is computed from the finding properties that are most important and characteristic. The hash is used implement a critical feature of AppMap Analysis - de-duplication. De-duplication serves two purposes:
+
+1) A finding may occur many times within a set of AppMap Diagrams. As a user, you're only interested in unique findings, therefore the hash can be used to de-duplicate the findings and present a minimal data set.
+2) Findings can be managed and triaged in the [AppMap Server](https://app.land) UI. For example, a finding can be deferred to prevent that finding from holding up a build or pull request. If the finding occurs again in the future, the hash is used to recognize that the finding has already been found, triaged - therefore the finding is not reported as new, and does not block the build or need to be re-triaged.

package/built/docs/guides/using-appmap-diagrams.md

@@ -0,0 +1,331 @@
+---
+layout: docs
+title: Docs - Guides
+description: "Configure AppMap Analysis by customizing checks for flexible rule options. Understand findings and their properties for effective analysis."
+guides: true
+toc: true
+name: Using AppMap Diagrams
+step: 2
+redirect_from: [/docs/how-to-use-appmap-diagrams.html, /docs/how-to-use-appmap-diagrams, /docs/diagrams/how-to-use-appmaps, /docs/diagrams/sequence-diagrams, /docs/diagrams, /docs/diagrams/how-it-works, /docs/diagrams/dependency-map, /docs/diagrams/trace-view, /docs/diagrams/sequence-diagram, /docs/diagrams/flamegraph, /docs/setup-appmap-in-your-code-editor/navigating-appmap-diagrams]
+---
+
+# Using AppMap Diagrams <!-- omit in toc -->
+
+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 right in your code editor, using the AppMap extension for your code editor. AppMap Diagrams also link directly to code, so you can use the information in the diagrams to make immediate code changes and improvements.
+
+- [How it Works](#how-it-works)
+- [Dependency Map](#dependency-map)
+- [Trace View](#trace-view)
+- [Sequence Diagram](#sequence-diagram)
+- [Flame Graph](#flame-graph)
+
+## How it Works <!-- omit in toc -->
+
+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 Data 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 AppMap Data](/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.
+
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/navigate-to-interest.mp4" type="video/mp4">
+  </video>
+</div>
+
+#### 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. 
+
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/filter-appmaps.mp4" type="video/mp4">
+  </video>
+</div>
+
+#### 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 AppMap Diagrams](/docs/guides/handling-large-appmap-diagrams) and to reduce their size. 
+
+<img src="/assets/img/docs/appmap-stats.webp"/>
+
+#### 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.  
+
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/sequence-diagram-expand.mp4" type="video/mp4">
+  </video>
+</div>
+
+#### Demo of using AppMap Diagrams
+This video demonstrates how to use AppMap Diagrams when learning how unfamiliar code works:
+
+<div style="position: relative; padding-bottom: 56.25%; height: 0;"><iframe src="https://www.loom.com/embed/de75ba638d57418da2d42417936cdf95" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
+
+## 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:
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/expand-and-collapse-packages.mp4" type="video/mp4">
+  </video>
+</div>
+
+#### View detailed information about dependencies and classes:
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/view-detailed-information-about-dependencies.mp4" type="video/mp4">
+  </video>
+</div>
+
+#### List the functions of a class that are used by the executed code:
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/list-the-functions-of-a-class.mp4" type="video/mp4">
+  </video>
+</div>
+
+
+#### Explore callers and callees:
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/dependency-explore-callers-and-callees.mp4" type="video/mp4">
+  </video>
+</div>
+
+#### View SQL queries in dependency map:
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/view-sql-queries-in-dependency-map.mp4" type="video/mp4">
+  </video>
+</div>
+
+#### Open source code right to the line of any particular function:
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/open-source-from-dependency-map.mp4" type="video/mp4">
+  </video>
+</div>
+
+## 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
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/expand-and-collapse-execution-paths.mp4" type="video/mp4">
+  </video>
+</div>
+
+#### Explore callers and callees
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/trace-explore-callers-and-callees.mp4" type="video/mp4">
+  </video>
+</div>
+
+#### View variable names and values at any point in the code flow
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/view-variable-names-and-values.mp4" type="video/mp4">
+  </video>
+</div>
+
+#### View SQL queries
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/view-sql-queries.mp4" type="video/mp4">
+  </video>
+</div>
+
+#### Open source code right to the line of any particular function
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/open-source-code-right-to-the-line.mp4" type="video/mp4">
+  </video>
+</div>
+
+## 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 AppMap Diagrams 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 AppMap Data 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) 
+
+## 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 Data recording, and it contains the recordings’s name. For an AppMap Flame Graph 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.
+
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/flamegraph-6.mp4" type="video/mp4">
+  </video>
+</div>
+
+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.
+
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/flamegraph-2.mp4" type="video/mp4">
+  </video>
+</div>
+
+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)