@appland/appmap 3.133.0 → 3.134.0

package/built/docs/diagrams/index.md

@@ -0,0 +1,20 @@
+---
+layout: docs
+title: Docs - Diagrams
+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 %}

package/built/docs/diagrams/sequence-diagram.md

@@ -0,0 +1,75 @@
+---
+layout: docs
+title: Docs - Diagrams
+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) 

package/built/docs/diagrams/trace-view.md

@@ -0,0 +1,55 @@
+---
+layout: docs
+title: Docs - AppMap Diagrams - Trace View
+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
+<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>

package/built/docs/guides/configuring-analysis.md

@@ -0,0 +1,157 @@
+---
+layout: docs
+title: Docs - Guides
+guides: true
+name: Configuring Analysis
+step: 6
+redirect_from: [/docs/analysis/match-pattern-config, /docs/analysis/findings,/docs/reference/configuring-analysis]
+---
+
+# Configuring Analysis <!-- omit in toc -->
+
+- [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)
+
+
+## Configuring 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 AppMaps. 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/handling-large-appmaps.md

@@ -0,0 +1,43 @@
+---
+layout: docs
+title: Docs - Guides
+guides: true
+name: Handling Large AppMaps
+step: 2
+redirect_from: [/docs/reference/handling-large-appmaps]
+---
+
+# Handling Large AppMaps <!-- omit in toc -->
+
+Some AppMaps contain too much data and can be difficult to review. Often, these AppMaps have many repetitive function calls that add a lot of data to the file, but don't add much value when interpreting the AppMap. Large AppMaps are a potential indication that you should change how you're recording by filtering out less valuable information. For example, you could exclude some calls to logging functions, or record fewer endpoints when manually recording.
+
+- [AppMaps Over 10 MB](#appmaps-over-10-mb)
+- [AppMaps Over 200 MB](#appmaps-over-200-mb)
+
+## AppMaps Over 10 MB
+
+When you attempt to open an AppMap in a code editor extension that is over 10 MB, it will be automatically pruned down to ~10 MB. The most frequently called functions will be removed until the file is below 10 MB in size. (Don't worry, the file will remain untouched because the pruning is done in memory).  You will see notifications within the AppMap informing you that it has been pruned, and the pruned functions will be highlighted in the Stats panel:
+
+![Pruned Stats Panel](/assets/img/docs/pruned_stats_panel.webp)
+
+The automatic pruning might be sufficient, but if you want more control over what events are removed, you have two options:
+
+1. [Use the `prune` CLI command to remove events from an existing AppMap](/docs/reference/appmap-client-cli.html#prune)
+2. Change the configuration of your `appmap.yml` to exclude certain events when an AppMap is generated
+    * [Configure exclusions in a Ruby project](/docs/reference/appmap-ruby.html#configuration)
+    * [Configure exclusions in a Java project](/docs/reference/appmap-java.html#configuration)
+    * [Configure exclusions in a Python project](/docs/reference/appmap-python.html#configuration)
+    * [Configure exclusions in a Node.js project](/docs/reference/appmap-node.html#configuration)
+
+## AppMaps Over 200 MB
+
+When an AppMap is over 200 MB, we will **not** open it in the code editor extension because it could cause performance issues on your computer. Instead, we generate statistics about your AppMap and open the Stats panel. Use this information to configure your `appmap.yml` to exclude these functions (see below). The next time that you generate your AppMap, it will be smaller because it will not contain the specified functions:
+
+![Giant Map Stats Panel](/assets/img/docs/giant_map_stats_panel.jpg)
+
+* [Configure exclusions in a Ruby project](/docs/reference/appmap-ruby.html#configuration)
+* [Configure exclusions in a Java project](/docs/reference/appmap-java.html#configuration)
+* [Configure exclusions in a Python project](/docs/reference/appmap-python.html#configuration)
+* [Configure exclusions in a Node.js project](/docs/reference/appmap-node.html#configuration)
+
+We do not recommend using the `prune` CLI command for AppMaps over 200 MB, because it loads the entire AppMap into memory, which may cause performance issues for your computer. 

package/built/docs/guides/index.md

@@ -0,0 +1,17 @@
+---
+layout: docs
+title: Docs - How-To Guides
+step: 1
+---
+
+# How-To Guides
+
+These guide contain in-depth information on how to use AppMap for different use cases and scenarios.
+
+- [Handling Large AppMaps](/docs/guides/handling-large-appmaps)
+- [Reading SQL in AppMaps](/docs/guides/reading-sql-in-appmaps)
+- [Refining AppMaps](/docs/guides/refine-appmaps)
+- [Generating OpenAPI Definitions](/docs/guides/openapi)
+- [Configuring Analysis](/docs/guides/configuring-analysis)
+- [Reverse Engineering with AppMap](/docs/guides/reverse-engineering)
+- [Understanding the Runtime Code Review Report](/docs/guides/runtime-code-review)

package/built/docs/guides/openapi.md

@@ -0,0 +1,104 @@
+---
+layout: docs
+title: Docs - Guides
+guides: true
+name: Generating OpenAPI Definitions
+step: 5
+redirect_from: [/docs/openapi,/docs/openapi/features,/docs/openapi/code-editor-extensions,/docs/openapi/integrations,/docs/openapi/customization,/docs/reference/openapi]
+---
+
+
+# Generating OpenAPI Definitions <!-- omit in toc -->
+
+> "The OpenAPI specification, which is formerly known as Swagger Specification, is a community-driven open standard, programming language-agnostic interface description for HTTP APIs. This allows both humans and computers to discover and understand the capabilities of a service without requiring access to the source code."
+
+Because AppMap records your code's runtime behavior, it can see and record all of the HTTP API calls processed including the schema of each request and response. Creating OpenAPI definitions by hand is error prone and time consuming. Keeping them up to date is additional work that quickly falls out of sync with the code. Using the AppMap we can automatically output OpenAPI definitions for an application. 
+
+- [Requirements](#requirements)
+- [Schema](#schema)
+- [Use Cases](#use-cases)
+  - [Pull Request Review](#pull-request-review)
+  - [Update Documentation Automatically](#update-documentation-automatically)
+  - [Send to 3rd Party Services](#send-to-3rd-party-services)
+- [Generating definitions](#generating-definitions)
+- [Integrations](#integrations)
+- [Customization](#customization)
+  - [Operation `summary`](#operation-summary)
+
+## Requirements
+
+1. AppMaps for your application that includes calls to your API endpoints. (Refer to the AppMap documentation on [how to record your application](/docs/recording-methods))
+2. The latest version of the [AppMap binaries downloaded.](https://github.com/getappmap/appmap-js/releases?q=@appland/appmap*&expanded=true) (For the CLI usage)
+3. The latest version of the AppMap code editor extension (for code editor usage)  
+
+## Schema
+
+The generated OpenAPI schema only includes information (paths, methods, status codes, parameters, responses, headers, security) that have actually been observed in the AppMap data. So, if a particular code behavior has not been observed by AppMap, it won't be present in the OpenAPI. 
+
+When AppMap data is collected by running test cases, the generated OpenAPI will reflect the code coverage of the application with regard to its APIs. If an expected path, method, status or parameter is not observed in the generated OpenAPI, you'll know it's missing because it's not tested.
+
+Object schema is inferred from runtime data. When there are many examples of a request, the inferred schema of all the examples is merged into one unified schema. 
+
+Both request and response schema are available.
+
+## Use Cases
+
+### Pull Request Review
+
+We suggest you generate OpenAPI for all new work, and commit the _openapi.yaml_ file to source control. When a pull request contains API changes, a diff view of the OpenAPI changes is a very useful way for code reviewers to quickly get the "big picture" of the new branch.
+
+### Update Documentation Automatically
+
+By generating OpenAPI definitions as part of your continuous integration process, you can ensure that your documentation continually updates automatically as the code updates. This reduces unnecessary engineering toil working to keep documentation up to date manually. 
+
+### Send to 3rd Party Services
+
+Integrate AppMap OpenAPI generation with various 3rd party services to share OpenAPI documentation with your end users or validate and diff changes over time.  [Refer to the documentation](/docs/integrations/) to learn how to incorporate AppMap OpenAPI generation with various 3rd party services.
+
+## Generating definitions
+
+* [AppMap extension for VSCode](/docs/reference/vscode.html#generate-openapi-definitions)
+* [AppMap extension for JetBrains](/docs/reference/jetbrains.html#generate-openapi-definitions)
+* [AppMap CLI](/docs/reference/appmap-client-cli.html#openapi)
+
+## Integrations
+
+Refer to the AppMap [integrations documentation](/docs/integrations/) to learn more about how to integrate your OpenAPI documentation with other 3rd party software and services. 
+
+## Customization
+
+### Operation `summary`
+
+To populate [`operation.summary`](https://swagger.io/specification/#operation-object), set the header `X-OpenAPI-Summary` in your response.
+
+**Example**
+
+_Ruby on Rails Controller_
+
+```
+class AccountActivationsController < ApplicationController
+  def edit
+    response.headers['X-OpenAPI-Summary'] = 'Activate the account of an existing user'
+```
+
+_openapi.yaml_
+
+```
+/account_activations/{id}/edit:
+    get:
+      responses:
+        '302':
+          content: {}
+          description: Found
+      parameters:
+        - name: email
+          in: query
+          schema:
+            type: string
+        - name: id
+          in: path
+          schema:
+            type: string
+          required: true
+      summary: Activate the account of an existing user
+```

package/built/docs/guides/reading-sql-in-appmaps.md

@@ -0,0 +1,67 @@
+---
+layout: docs
+title: Docs - Guides
+guides: true
+name: Reading SQL in AppMaps
+step: 3
+---
+
+## Reading SQL in AppMaps
+The AppMap extension for your editor displays SQL commands in AppMap Diagrams so you can understand how your application logic interacts with the database. You can quickly discover SQL inefficiencies and anti-patterns that pose hidden scalability and reliability risks even if your application seems to be working well.
+
+With the AppMap extension, not only are trips to database logs no longer required to see the SQL commands, but the SQL commands are also directly linked to the code that initiates their execution, helping developers understand the direct impacts of their code updates on database operations and performance.   
+
+### View all SQL commands, pick a command of interest, and drill down to details
+When you open an AppMap, the navigation bar lists all captured SQL commands. This is a great starting point for your SQL investigation: 
+- Browse the list of SQL commands, pick a command, and click on it to drill down to details
+- View the SQL command in the Trace to see how it is connected to upstream/downstream code and other SQL commands
+- Click on the Caller link to see the function call that initiated the command’s execution.
+
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/view-all-sql-commands.mp4" type="video/mp4">
+  </video>
+</div>
+
+### Search for specific SQL commands/tables/columns
+Use the search box in the Navigation bar to select for a specific subset of SQL Commands: 
+- Search for a specific SQL command such as SELECT, UPDATE, INSERT, etc.
+- Search for a table or column name
+- Use regular expressions for complex searches, filtering the results by multiple criteria, for example, `SELECT.*_orders.*`
+
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/search-for-specific-sql-commands.mp4" type="video/mp4">
+  </video>
+</div>
+
+### View SQL commands executed by a specific class or package
+When you click on a dependency link in the Dependency Map, the navigation bar will list events specific to that relationship. 
+- Select a link between the database icon and a class to see SQL commands executed by functions of that class
+- Click on a SQL command to drill down to details.
+
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/view-specific-sql-executed-by-class.mp4" type="video/mp4">
+  </video>
+</div>
+
+### Spot complex SQL patterns
+When investigating how efficiently the application code or the ORM utilizes the database, it’s helpful to see whether multiple SQL commands are clustered together and whether they form any specific (anti-)patterns. The Trace view is a great visual tool for spotting clusters and repetitions of SQL commands enveloped by code that are difficult to discover using database logs or other simple tools.
+- In the AppMap, switch to the Trace view
+- Start with any of the SQL commands in the navigation bar and investigate how they are connected with other SQL commands or code blocks
+- When looking for N+1-like patterns, look for repetitive SQL `SELECT`s fetching single records using a specific ID
+- Use the zoom controls, arrow keys, panning, and expand/collapse functions to navigate around the trace efficiently.
+
+#### Navigate the trace efficiently
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/navigate-the-trace-efficiently.mp4" type="video/mp4">
+  </video>
+</div>
+
+
+### Example: How to spot and fix Django ORM anti-patterns
+In this video example, you can learn how to optimize Django ORM by seeing how it makes SQL queries under the hood. The video explains the role of ORM in modern applications, SQL efficiency challenges, and how to use AppMap for uncovering and fixing the infamous N+1 anti-pattern
+
+<div style="position: relative; padding-bottom: 56.25%; height: 0;"><iframe src="https://www.loom.com/embed/3872950e96174da4a714211b2af7f56e" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>