@appland/appmap 3.143.0 → 3.145.0

package/built/docs/guides/openapi.md

@@ -1,105 +0,0 @@
----
-layout: docs
-title: Docs - Guides
-description: "Use AppMap to auto generate OpenAPI definitions and document HTTP APIs. AppMap captures runtime behavior, creating accurate API schemas effortlessly."
-guides: true
-name: Generating OpenAPI Definitions
-step: 7
-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. AppMap Data generated from 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-appmap-diagrams.md

@@ -1,69 +0,0 @@
----
-layout: docs
-title: Docs - Guides
-description: "Discover SQL commands in AppMap Diagrams to analyze application logic's database interactions, spot inefficiencies, and understand code impacts for improved performance and reliability."
-guides: true
-name: Reading SQL in AppMap Diagrams
-step: 5
-redirect_from: [/docs/guides/reading-sql-in-appmaps]
----
-
-## Reading SQL in AppMap Diagrams
-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>

package/built/docs/guides/refine-appmap-data.md

@@ -1,186 +0,0 @@
----
-layout: docs
-title: Docs - Guides
-description: "Optimize AppMap Diagrams by refining recordings to exclude noise. Start with inclusive config, analyze stats, update config, create concise AppMap Diagrams."
-guides: true
-name: Refining AppMap Data
-step: 6
-redirect_from: [/docs/reference/refine-appmaps, /docs/guides/refine-appmaps]
----
-
-# Refining AppMap Data <!-- omit in toc -->
-
-When you initially create a client configuration, it can be hard to know what classes to
-include. Most often, you will simply select everything just to see what a recording looks
-like. The resulting AppMap Diagrams can be quite large and noisy. The presence of calls to many
-utility methods makes it hard to understand the bigger picture.
-
-To refine your recordings, it's best to start with the smallest use-case that's
-representative of the entire application. For example, while a single unit test will
-produce a small recording, such tests typically avoid accessing external resources
-(e.g. web services, a database, or the file system) for the sake of speed. Recording a
-single functional or integration test is a better choice.
-
-Once you've made a recording of a use-case, you can use the `stats` subcommand
-of the [AppMap CLI](/docs/reference/appmap-client-cli.html).
-tools to generate some simple statistics about your AppMap Data. Based on these statistics,
-you will be able to update your configuration so that less-interesting methods are
-excluded. When new recordings are created with the improved configuration, they will be
-more concise and easier to understand.
-
-To illustrate the refinement process, we'll look at a recording made for
-[Jenkins](https://github.com/land-of-apps/jenkins). [CONTRIBUTING.md](https://github.com/land-of-apps/jenkins/blob/master/CONTRIBUTING.md#testing-changes)
-in that repository mentions that there are functional tests in the `test` module. For this
-example, we'll use the tests in
-[test/src/test/java/hudson/model/DirectlyModifiableViewTest.java](https://github.com/land-of-apps/jenkins/blob/master/test/src/test/java/hudson/model/DirectlyModifiableViewTest.java).
-
-- [Step 1: Make a recording with an inclusive configuration](#step-1-make-a-recording-with-an-inclusive-configuration)
-- [Step 2: Eliminate the noise](#step-2-eliminate-the-noise)
-- [Step 3: Update the configuration and create new AppMap Diagrams](#step-3-update-the-configuration-and-create-new-appmap-diagrams)
-
-## Step 1: Make a recording with an inclusive configuration
-
-We'll start with a very broad configuration specified in
-`appmap.yml`:
-
-```yaml
-name: Jenkins
-packages:
-- path: org.acegisecurity.context
-- path: hudson
-- path: jenkins
-```
-{: .example-code}
-
-These are the three top-level packages used by Jenkins. We include them to make sure all
-calls to methods that might be interesting get recorded.
-
-Running the tests in `DirectlyModifiableViewTest.java` produces five very large AppMap Diagrams:
-
-```
-% mvn test -Dtest=DirectlyModifiableViewTest
-...
-% ls -lsh | sort -n
-total 310312
- 11456 -rw-r--r--  1 ajp  staff   5.6M Nov 11 10:04 hudson_model_DirectlyModifiableViewTest_manipulateViewContent.appmap.json
- 32952 -rw-r--r--  1 ajp  staff    16M Nov 11 10:04 hudson_model_DirectlyModifiableViewTest_doAddJobToView.appmap.json
- 41240 -rw-r--r--  1 ajp  staff    20M Nov 11 10:04 hudson_model_DirectlyModifiableViewTest_doRemoveJobFromView.appmap.json
-109864 -rw-r--r--  1 ajp  staff    53M Nov 11 10:04 hudson_model_DirectlyModifiableViewTest_doAddNestedJobToRecursiveView.appmap.json
-114800 -rw-r--r--  1 ajp  staff    56M Nov 11 10:05 hudson_model_DirectlyModifiableViewTest_failWebMethodForIllegalRequest.appmap.jso
-```
-
-The statistics for these show that there's substantial noise in them:
-
-```
-% appmap stats tmp/appmap
-232356 calls, top 20 methods
-  hudson.util.AdaptedIterator#hasNext:50: 30433 (1 distinct)
-  hudson.util.Iterators$5#hasNext:295: 30433 (1 distinct)
-  hudson.ExtensionComponent#getInstance:73: 25040 (1 distinct)
-  hudson.util.AdaptedIterator#next:54: 24779 (1 distinct)
-  hudson.util.Iterators$5#next:299: 24779 (1 distinct)
-  jenkins.model.Jenkins$3#getInstance:763: 8101 (1 distinct)
-  jenkins.security.stapler.StaticRoutingDecisionProvider#decide:85: 7913 (1838 distinct)
-  jenkins.model.Jenkins#getExtensionList:2702: 5963 (15 distinct)
-  hudson.ExtensionList#iterator:172: 5849 (1 distinct)
-  hudson.util.Iterators.readOnly:293: 5849 (5849 distinct)
-  hudson.ExtensionList.lookup:433: 5831 (14 distinct)
-  hudson.ExtensionList#size:191: 5452 (1 distinct)
-  jenkins.security.stapler.DoActionFilter#keep:54: 2445 (2445 distinct)
-  jenkins.security.stapler.TypedFilter#keep:193: 2352 (2352 distinct)
-  jenkins.model.Jenkins.get:775: 1702 (1 distinct)
-  hudson.util.RobustReflectionConverter$1#visit:193: 1517 (122 distinct)
-  hudson.util.RobustReflectionConverter$2#visit:211: 1517 (122 distinct)
-  hudson.util.xstream.MapperDelegate#getConverterFromItemType:103: 1517 (28 distinct)
-  hudson.util.xstream.MapperDelegate#getConverterFromItemType:123: 1517 (73 distinct)
-  hudson.util.xstream.MapperDelegate#getConverterFromItemType:95: 1517 (67 distinct)
-```
-
-The top 20 methods in these files are called more than 1500 times! Removing them from the
-recordings will make the AppMap Diagrams easier to understand, without eliminating any
-interesting information.
-
-## Step 2: Eliminate the noise
-
-We'll start by generating more detailed statistics:
-
-```sh
-% appmap stats --limit 0 --files --json tmp/appmap > jenkins-unfiltered-stats.json
-```
-{: .example-code}
-
-The output will contain statistics for all calls in all files, formatted as JSON.
-
-Next, examine the statistics to look for methods that can be considered for exclusion:
-
-```
-% jq -r '.totals[] | select(.calls > 75) | "  - \(.method)"' jenkins-unfiltered-stats.json | sort | uniq > exclusions.yml
-% grep hudson exclusions.yml | head -5
-  - hudson.ExpressionFactory2#createExpression
-  - hudson.ExpressionFactory2$JellyJexlContext#getVars
-  - hudson.ExpressionFactory2$JellyMap#get
-  - hudson.ExpressionFactory2$JexlExpression#evaluate
-  - hudson.ExtensionComponent#getInstance
-% grep jenkins exclusions.yml | head -5
-  - jenkins.MetaLocaleDrivenResourceProvider#lookup
-  - jenkins.model.Jenkins#getACL
-  - jenkins.model.Jenkins#getAuthorizationStrategy
-  - jenkins.model.Jenkins#getCrumbIssuer
-  - jenkins.model.Jenkins#getDescriptor
-```
-
-This finds methods that are called more than 75 times and saves them in a useful
-form. Sorting them makes them easier to include in `appmap.yml`. Duplicate
-method names will appear in the recording because of method overloading, but it's not
-necessary to list them separately in the configuration. They can be removed.
-
-Note that there's nothing special about the 75-call threshold used to select calls for
-exclusion. Depending on your application, a different value may produce better results.
-
-## Step 3: Update the configuration and create new AppMap Diagrams
-
-The new configuration in `appmap.yml` gets updated to look like this:
-
-```
-name: Jenkins
-packages:
-- path: org.acegisecurity.context
-  exclude:
-  - org.acegisecurity.context.SecurityContextHolder.setContext
-  - org.acegisecurity.context.SecurityContextImpl#getAuthentication
-  - org.acegisecurity.context.ThreadLocalSecurityContextHolderStrategy#getContext
-  - org.acegisecurity.context.ThreadLocalSecurityContextHolderStrategy#setContext
-
-- path: hudson
-  exclude:
-  - hudson.ExpressionFactory2#createExpression
-  - hudson.ExpressionFactory2$JellyJexlContext#getVars
-  - hudson.ExpressionFactory2$JellyMap#get
-  - hudson.ExpressionFactory2$JexlExpression#evaluate
-...
-- path: jenkins
-  exclude:
-  - jenkins.MetaLocaleDrivenResourceProvider#lookup
-  - jenkins.model.Jenkins#getACL
-  - jenkins.model.Jenkins#getAuthorizationStrategy
-  - jenkins.model.Jenkins#getCrumbIssuer
-...
-```
-
-
-where the `exclude` sections should contain all the appropriate exclusions from
-`exclusions.yml`.
-    
-With the configuration in place, rerun the tests and see the results:
-
-```
-% mvn test  -Dtest=NodeCanTakeTaskTest
-...
-% ls -lsh tmp/appmap | sort -n
-total 11176
- 776 -rw-r--r--  1 ajp  staff   329K Nov 11 10:41 hudson_model_DirectlyModifiableViewTest_doRemoveJobFromView.appmap.json
- 776 -rw-r--r--  1 ajp  staff   370K Nov 11 10:41 hudson_model_DirectlyModifiableViewTest_doAddJobToView.appmap.json
-1416 -rw-r--r--  1 ajp  staff   693K Nov 11 10:41 hudson_model_DirectlyModifiableViewTest_manipulateViewContent.appmap.json
-4104 -rw-r--r--  1 ajp  staff   1.3M Nov 11 10:41 hudson_model_DirectlyModifiableViewTest_doAddNestedJobToRecursiveView.appmap.json
-4104 -rw-r--r--  1 ajp  staff   1.8M Nov 11 10:41 hudson_model_DirectlyModifiableViewTest_failWebMethodForIllegalRequest.appmap.json
-```