@appland/appmap 3.133.0 → 3.134.0

package/built/docs/reference/appmap-java.md

@@ -0,0 +1,310 @@
+---
+layout: docs
+title: Docs - Reference
+toc: true
+reference: true
+name: AppMap Agent for Java
+step: 5
+---
+
+# AppMap Agent for Java
+
+- [About](#about)
+  - [Supported versions](#supported-versions)
+- [Tests recording](#tests-recording)
+  - [Using IntelliJ IDEA Run Configurations](#using-intellij-idea-run-configurations)
+  - [Recording tests with Maven](#recording-tests-with-maven)
+  - [Recording tests with Gradle](#recording-tests-with-gradle)
+  - [Other build systems](#other-build-systems)
+- [Requests recording](#requests-recording)
+  - [Requests recording in Spring Boot and Spring Web Framework](#requests-recording-in-spring-boot-and-spring-web-framework)
+  - [Requests recording in Spark Framework](#requests-recording-in-spark-framework)
+- [Remote recording](#remote-recording)
+- [Process recording](#process-recording)
+- [Code Block Recording](#code-block-recording)
+- [Configuration](#configuration)
+- [Annotations](#annotations)
+  - [@Labels](#labels)
+    - [Usage](#usage)
+  - [@NoAppMap](#noappmap)
+    - [Usage](#usage-1)
+- [System Properties](#system-properties)
+- [GitHub repository](#github-repository)
+
+## About
+
+`appmap-agent` is a Java agent JAR for recording [AppMaps](https://github.com/getappmap/appmap) of your code. 
+
+{% include docs/what_is_appmap_snippet.md %}
+
+### Supported versions
+
+{% include docs/java_support_matrix.html %}
+
+## Tests recording
+
+### Using IntelliJ IDEA Run Configurations
+
+If you're using JetBrains IntelliJ IDEA, we recommend using [run configurations to create AppMaps](/docs/reference/jetbrains#create-appmaps-with-tests).
+
+### Recording tests with Maven
+
+Alternatively, you may record your tests with the
+[AppMap Maven plugin](/docs/reference/appmap-maven-plugin#installation).
+
+### Recording tests with Gradle
+
+Alternatively, you may record your tests with the
+[AppMap Gradle plugin](/docs/reference/appmap-gradle-plugin#installation).
+
+### Other build systems
+
+You can download the latest release of `appmap-agent-<version>.jar` from [https://mvnrepository.com/artifact/com.appland/appmap-agent/latest](https://mvnrepository.com/artifact/com.appland/appmap-agent/latest).
+
+Both the AppMap plugin for IntelliJ and the AppMap extension for VS Code automatically download
+the latest the AppMap Java agent, and store it locally in `$HOME/.appmap/lib/java/appmap.jar`.
+
+The recorder is run as a Java agent. Currently, it must be started along with
+the JVM. This is done by passing the `-javaagent` argument to your
+JVM when recording tests. For example:
+
+```shell
+$ java -javaagent:$HOME/.appmap/lib/java/appmap.jar myapp.jar
+```
+
+## Requests recording
+`appmap-java` can automatically record and save an AppMap for each HTTP server request which it processes. This functionality is currently supported for applications built using [Spring Boot](https://spring.io/projects/spring-boot), Servlet-stack web applications built using [Spring Framework](https://docs.spring.io/spring-framework/reference/web.html), and [Spark Framework](http://sparkjava.com/).
+
+### 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 Web Framework, `appmap-java` adds the listener when Spring's servlet container is initialized.
+
+### Requests recording in Spark Framework
+For Spark Framework, `appmap-java` wraps Sparks' Handler with a HandlerWrapper that manages recording.
+
+## Remote recording
+
+`appmap-java` supports the [AppMap remote recording API](/docs/reference/remote-recording-api).
+This functionality is provided by the AppMap agent. It will hook into the Java servlets API, injecting the remote recording routes into the servlet chain.
+
+**Note** Your application must be running in a servlet container (e.g. Tomcat, Jetty, etc.) for remote recording to work.
+
+1. Start your application with the AppMap agent enabled
+   1. [IntelliJ - "Start with Appmap"](/docs/reference/jetbrains.html#start-with-appmap-for-java)
+   2. Command line - run your Servlet-based application with the `javaagent` JVM argument:
+
+```shell
+$ java -javaagent:$HOME/.appmap/lib/java/appmap.jar -jar target/*.jar
+```
+
+2. Start and stop the recording
+   1. [IntelliJ](/docs/reference/jetbrains.html#remote-recording)
+   2. [VSCode](/docs/reference/vscode.html#remote-recording)
+
+## Process recording
+
+`appmap-java` can record an entire Java process from start to finish.
+
+1. Set the Java system property `appmap.recording.auto=true`. You must set this system property as a JVM argument.
+  If you are using a graphical run configuration, add the option `-Dappmap.recording.auto=true` to the "VM options" field.
+  If you are running on the command line, add the option `-Dappmap.recording.auto=true` to the JVM CLI arguments.
+
+2. Start your application with the AppMap agent enabled using one of these approaches:
+   1. [IntelliJ - "Start with Appmap"](/docs/reference/jetbrains.html#start-with-appmap-for-java)
+   2. Command line - run your Servlet-based application with the `javaagent` JVM argument:
+
+```shell
+$ 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
+
+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.
+
+This code snippet illustrates how to use the `record()` function to record a block of code, and then write the AppMap data to a file:
+
+```java
+final Recorder recorder = Recorder.getInstance();
+
+final MyClass myClass = new MyClass();
+Recording recording = recorder.record(() -> {
+  for (int i = 0; i < 10; i++) {
+    myClass.myMethod();
+  }
+});
+StringWriter sw = new StringWriter();
+recording.readFully(true, sw);
+
+// Now write the recorded AppMap data to a file. The file name should end in ".appmap.json".
+try (PrintWriter out = new PrintWriter("runnable-recording.appmap.json")) {
+  out.println(sw.toString());
+}
+catch (FileNotFoundException ex) {
+  ex.printStackTrace();
+  System.exit(1);
+}
+```
+{: .example-code}
+
+
+## Configuration
+
+When you run your program, the agent reads configuration settings from
+`appmap.yml`. Here's a sample configuration file for a typical Java project:
+
+```
+# 'name' should generally be the same as the code repo name.
+name: MyProject
+language: java
+appmap_dir: tmp/appmap
+packages:
+- path: com.mycorp.myproject
+  exclude: [ com.mycorp.myproject.MyClass#MyMethod ]
+- path: org.springframework.web
+  shallow: true
+  exclude: 
+  - org.springframework.web.util
+- path: java.util.logging
+  methods:
+  - class: Logger
+    name: log
+
+```
+
+- **name** Provides the project name (required)
+- **appmap_dir** The directory where AppMaps will be saved by request recording. If unset, a default based on the project's build configuration file will be used.
+- **packages** A list describing how packages should be instrumented. For backwards compatibility, classes and methods can also be specified here. New projects should use the `methods` property to specify which methods to instrument.
+
+**packages**
+
+Each entry in the `packages` list is a YAML object which has the following keys:
+
+* **path** A Java package, class, or method that will be instrumented.
+* **exclude** A list of fully-qualified sub-packages, sub-classes
+  and sub-methods that will be ignored. The exclude list only applies to the
+  `path` specified in the same package entry.
+
+* **shallow** When set to `true`, only the first function call entry into a
+  package will be recorded. Subsequent function calls within the same package
+  are not recorded unless code execution leaves the package and re-enters it.
+  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 
+  * **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.
+
+Each of the **class** and **name** regular expressions is a
+[java.util.regex.Pattern
+](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html). They
+will be surrounded with `\A(` `)\z` to match whole symbols. This means, in the
+example above, `log` will match exactly that method of `Logger`, but not the
+`logp` or `logrb` methods. To match all three methods, use `log(|p|rb)` or
+`log.*`. To include the literal symbols `.` or `$` in the patterns, they must be
+properly escaped: `\.` or `\$`.
+
+If the **methods** attribute is specified for a package, each element in the
+list will be matched in the order specified, and only the matching methods will
+be instrumented. When the **methods** attribute is set, the **exclude**
+attribute is ignored.
+
+## Annotations
+The `appmap-java` annotations are provided in the package `com.appland:appmap-annotation`, available on [Maven Central](https://search.maven.org/artifact/com.appland/appmap-annotation). To use them, add that package as a dependency in your build configuration file (`pom.xml`, `build.gradle`).
+
+### @Labels
+`appmap-java` suports the addition of [code labels](https://appmap.io/docs/appmap-overview.html#features) through the `com.appland.appmap.annotation.Labels` annotation.
+
+#### Usage
+Once the `Labels` annotation is available, you can apply it to methods in your application. For example:
+
+```
+import com.appland.appmap.annotation.Labels;
+
+public class ExampleClass {
+  ...
+  @Labels({"label1", "label2"})
+  public void labeledFunction() {
+    ...
+  }
+}
+```
+
+When `labeledFunction` appears in an AppMap, it will have the labels `label1` and `label2`.
+
+### @NoAppMap
+The `NoAppMap` annotation can be used to disable recording of JUnit test methods. If applied to a specific method, that method will not generate an AppMap. Alternatively, it can be applied to a test class to disable generation of AppMaps for all test methods in the class.
+
+#### Usage
+Example of annotating a test method:
+
+```
+import com.appland.appmap.annotation.NoAppMap;
+...
+
+public class TestClass {
+  @Test
+  public void testMethod1() {
+    ...
+  }
+
+  @NoAppMap
+  @Test
+  public void testMethod2() {
+    ...
+  }
+}
+```
+`testMethod1` will generate an AppMap, and `testMethod2` will not.
+
+Example of annotating a test class:
+```
+import com.appland.appmap.annotation.NoAppMap;
+...
+
+@NoAppMap
+public class UnrecordedTestClass {
+  @Test
+  public void testMethod1() {
+    ...
+  }
+
+  @Test
+  public void testMethod2() {
+    ...
+  }
+}
+```
+No AppMaps will be generated for the tests in `UnrecordedTestClass`.
+
+## System Properties
+
+- `appmap.config.file` Path to the `appmap.yml` config file. Default:
+  _appmap.yml_
+- `appmap.output.directory` Output directory for `.appmap.json` files. Default:
+  `./tmp/appmap`
+- `appmap.debug` Enable debug logging. Default: `null` (disabled)
+- `appmap.event.valueSize` Specifies the length of a value string before
+  truncation occurs. If set to `0`, truncation is disabled. Default: `1024`
+- `appmap.record.private` Record private methods, as well as methods with
+  package and protected access. Default: `false` (no private methods will be
+  recorded).
+- `appmap.recording.auto` Automatically begin recording at boot time. Default:
+  `false`
+- `appmap.recording.file` The file name of the automatic recording to be
+  emitted. Note that the file name will still be prefixed by
+- `appmap.recording.requests` If `true`, create a recording for each HTTP server request (for
+  supported frameworks). Default: `true`.
+  `appmap.output.directory`. Default: `$TIMESTAMP.appmap.json`
+- `appmap.recording.name` Populates the `metadata.name` field of the AppMap.
+  Default: `$TIMESTAMP`
+
+
+## GitHub repository
+
+[https://github.com/getappmap/appmap-java](https://github.com/getappmap/appmap-java)
+

package/built/docs/reference/appmap-maven-plugin.md

@@ -0,0 +1,163 @@
+---
+layout: docs
+title: Docs - Reference
+toc: true
+reference: true
+name: AppMap for Java - Maven Plugin
+step: 6
+---
+
+# AppMap Maven plugin
+
+- [AppMap Maven plugin](#appmap-maven-plugin)
+  - [About](#about)
+  - [Installation](#installation)
+  - [Tests recording](#tests-recording)
+  - [Plugin goals](#plugin-goals)
+  - [Plugin configuration](#plugin-configuration)
+  - [Configuring Surefire](#configuring-surefire)
+  - [Troubleshooting](#troubleshooting)
+  - [Running without modifying `pom.xml`](#running-without-modifying-pomxml)
+  - [GitHub repository](#github-repository)
+
+## About
+
+The AppMap Maven Plugin provides simple method for recording AppMaps in running
+tests in Maven projects and a seamless integration into CI/CD pipelines. The
+client agent requires `appmap.yml` configuration file, see
+[appmap-java](./appmap-java) for details.
+
+## Installation
+
+First, ensure you have a
+[properly configured `appmap.yml`](./appmap-java#configuration)
+in your root project directory.
+
+Next, add the following plugin definition to your `pom.xml`:
+```xml
+<!-- the appmap plugin element goes to build/plugins -->
+<plugin>
+    <groupId>com.appland</groupId>
+    <artifactId>appmap-maven-plugin</artifactId>
+    <version>${appmap.maven-plugin-version}</version>
+    <executions>
+        <execution>
+            <phase>process-test-classes</phase>
+            <goals>
+                <goal>prepare-agent</goal>
+            </goals>
+        </execution>
+    </executions>
+</plugin>
+```
+{: .example-code}
+
+## Tests recording
+
+The AppMap agent will automatically record your tests when you run
+```shell
+mvn test
+```
+{: .example-code}
+
+By default, AppMap files are output to `tmp/appmap`.
+
+## Plugin goals
+
+- `prepare-agent` - adds the AppMap Java agent to the JVM
+- `print-jar-path` - prints the path to the `appmap-agent.jar` file in the local Maven cache
+
+Example:
+```shell
+mvn com.appland:appmap-maven-plugin:print-jar-path
+```
+{: .example-code}
+
+or
+
+```shell
+mvnw com.appland:appmap-maven-plugin:print-jar-path
+```
+{: .example-code}
+
+## Plugin configuration
+
+- `configFile` Path to the `appmap.yml` config file. Default: _./appmap.yml_
+- `outputDirectory` Output directory for `.appmap.json` files. Default:
+  _./tmp/appmap_
+- `skip` Agent won't record tests when set to true. Default: _false_
+- `debug` Enable debug flags as a comma separated list. Accepts: `info`,
+  `hooks`, `http`, `locals` Default: _info_
+- `debugFile` Specify where to output debug logs. Default:
+  _tmp/appmap/agent.log_
+- `eventValueSize` Specifies the length of a value string before truncation
+  occurs. If set to 0, truncation is disabled. Default: _1024_
+
+  
+## Configuring Surefire
+Some configuration parameters of the Surefire plugin may prevent the appmap plugin
+from being activated when the tests are run:
+1. `forkCount` may not be set to `0`. Please set it to a value larger than `0` or
+remove this configuration parameter from `pom.xml`
+3. If `argLine` is specified, it must include `@{argLine}`
+
+Example:
+```
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-surefire-plugin</artifactId>
+    <version>${maven-surefire-plugin.version}</version>
+    <configuration>
+        <forkCount>1</forkCount>
+        <reuseForks>true</reuseForks>
+        <argLine>
+            @{argLine} --illegal-access=permit
+        </argLine>
+    </configuration>
+</plugin>
+```
+
+## Troubleshooting
+
+**I have no `tmp/appmap` directory**  
+  It's likely that the agent is not running. Double check the `prepare-agent`
+  goal is being run. If the JVM is being forked at any point, make sure the
+  `javaagent` argument is being propagated to the new process. Additionally
+  check that the Surefire plugin configuration is not preventing the agent
+  from running. See ["Configuring Surefire"](#configuring-surefire) for more
+  information.
+
+**`*.appmap.json` files are present, but appear empty or contain little data**  
+  Double check your `appmap.yml`. This usually indicates that the agent is
+  functioning as expected, but no classes or methods referenced in the
+  `appmap.yml` configuration are being executed. You may need to adjust the
+  packages being recorded. Follow this link for more information:
+  [AppMap java configuration](./appmap-java#configuration).
+
+**My tests aren't running or I'm seeing `The forked VM terminated without
+  properly saying goodbye.`**  
+  Check the agent log (defaults to `tmp/appmap/agent.log`) and/or the
+  Maven Surefire dumpstream (`target/surefire-reports/${DATETIME}.dumpstream`).
+  This is typically indicative of an invalid `appmap.yml` configuration.
+
+**I have a test failure that only occurs while the agent is attached**  
+  Please open an issue at [getappmap/appmap-java](https://github.com/getappmap/appmap-java/issues).
+  Attach a link to the source code or repository (if available), as well as any
+  other relevant information including:
+  - the contents of `appmap.yml`
+  - the run command used (such as `mvn test`)
+  - output of the run command
+  - any Maven Surefire dumpstreams generated
+    (`target/surefire-reports/${DATETIME}.dumpstream`)
+
+## Running without modifying `pom.xml`
+By specifying the fully-qualified goal, the agent can be run without any
+additional configuration:
+```sh
+mvn com.appland:appmap-maven-plugin:prepare-agent test
+```
+{: .example-code}
+
+## GitHub repository
+
+[https://github.com/getappmap/appmap-maven-plugin](https://github.com/getappmap/appmap-maven-plugin)

package/built/docs/reference/appmap-node.md

@@ -0,0 +1,185 @@
+---
+layout: docs
+title: Docs - Reference
+toc: true
+reference: true
+name: AppMap Agent for Node.js
+step: 5
+redirect_from: [/docs/reference/appmap-agent-js]
+---
+
+# AppMap Agent for Node.js
+
+**Note**: this agent is currently in early access. It replaces [appmap-agent-js](/docs/reference/appmap-agent-js) which is no longer in active development. [Let us know](https://github.com/getappmap/appmap-node/issues)
+if your project is unable to create AppMaps with `appmap-node`.
+
+- [About](#about)
+  - [Supported versions](#supported-versions)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [Tests recording](#tests-recording)
+  - [Recording Mocha, Jest, or Vitest test cases](#recording-mocha-jest-or-vitest-test-cases)
+- [Remote recording](#remote-recording)
+- [Process recording](#process-recording)
+- [Request recording](#request-recording)
+- [Viewing AppMaps](#viewing-appmaps)
+- [GitHub repository](#github-repository)
+- [Troubleshooing](#troubleshooting)
+
+## About
+
+`appmap-node` records [AppMaps](https://appmap.io) of your Node.js applications. 
+
+{% include docs/what_is_appmap_snippet.md %}
+
+### Supported versions
+
+{% include docs/node_support_matrix.html %}
+
+AppMap for Node.js can record applications written in both JavaScript and TypeScript.
+
+## Usage
+
+```
+npx appmap-node <launch command>
+```
+{: .example-code}
+
+AppMap for Node.js wraps your existing application launch command, and typically does not require
+any special installation or configuration. 
+
+For example, if your Node.js application is normally run with the command `npm run dev`, the following 
+command would create AppMap recordings of that application's behavior when it runs:
+
+```console
+$ npx appmap-node npm run dev
+```
+{: .example-code}
+
+The `appmap-node` command works by passing a modified version of the environment variable `NODE_OPTIONS`
+to the launch command. This allows it to work with any Node.js command, including ones based on `npm`,
+`npx`, `node`, or even shell scripts that launch Node.js applications.
+
+AppMaps are saved to the directory `tmp/appmap` by default, and each AppMap file ends in `.appmap.json`.
+
+## Configuration
+
+When you run your program, the agent reads configuration settings from `appmap.yml`. If not found, a default config file will be created. This is typically appropriate for most projects but you're welcome to review and adjust it.
+
+Here's a sample configuration file for a typical JavaScript project:
+
+```yaml
+name: MyApp
+appmap_dir: tmp/appmap
+packages:
+- path: .
+  exclude:
+  - node_modules
+  - .yarn
+```
+{: .example-code}
+
+- **name** Provides the project name (autodetected from *package.json*).
+- **appmap_dir** Directory to place the appmaps in. Defaults to `tmp/appmap`.
+- **packages** A list of paths which should be instrumented.
+
+**packages**
+
+Each entry in the `packages` list is a YAML object which has the following keys:
+
+- **path** A path to JavaScript source files; if the project is transpiled, this should include the final js files. Relative paths are resolved with respect to *appmap.yml* location.
+- **exclude** A list of path, functions and methods that will be ignored. The exclude list only applies to the *path* specified in the same package entry. Paths are resolved with respect to that *path*. For example:
+
+```yaml
+packages:
+- path: dist/users
+  exclude:
+  - util.js
+  - findUser
+  - UsersController.index
+- path: dist # catch-all to instrument the rest of the code
+```
+{: .example-code}
+
+## Tests recording
+
+When running test cases with `appmap-node`, a new AppMap file will be created for each unique test case.
+
+### Recording Mocha, Jest, or Vitest test cases
+
+Wrap your existing `mocha`, `jest`, or `vitest` test command with `appmap-node`. For example:
+
+```console
+$ npx appmap-node mocha specs/test.js
+$ npx appmap-node npm test
+$ npx appmap-node yarn test
+```
+{: .example-code}
+    
+When the tests are complete, the AppMaps will be stored in the default output directory `tmp/appmap/<test-framework>`,
+where `<test-framework>` will be one of `mocha`, `jest`, or `vitest`.
+
+{% include vimeo.html id='921256248' %}
+
+## Remote recording
+
+The `appmap-node` agent supports the [AppMap remote recording API](/docs/reference/remote-recording-api).
+AppMap adds HTTP APIs that can be used to toggle recording on and off after an application has started.
+Remote recording is useful when you'd like to record only during a specific time during your application's execution.
+
+1. Run `appmap-node` as normal, passing your application's starting command as the arguments.
+2. `appmap-node` will start the app and inject itself in its http stack. It will listen for [remote recording requests](/docs/reference/remote-recording-api).
+3. Start the remote recording:
+    - [in VS Code](/docs/reference/vscode.html#remote-recording)
+    - [in JetBrains IDEs](/docs/reference/jetbrains.html#remote-recording)
+    - [with curl](/docs/reference/remote-recording-api)
+4. Interact with your application's API or UI to so that those features get recorded.
+5. Stop the recording using the AppMap code editor plugin or curl to save the new AppMap to disk.
+
+{% include vimeo.html id='921270684' %}
+
+## Request Recording
+
+AppMap for Node.js supports Request Recording. This feature automatically records an AppMap for each HTTP request
+served by the application at runtime.
+
+Request recording occurs automatically once any HTTP requests are served, and does not require special
+configuration. Pass your application launch command as the argument to `npx appmap-node` and make HTTP requests
+to your application as normal. 
+
+Each API request served will create an AppMap representing the full processing of that single HTTP 
+request, and will be stored in `tmp/appmap/requests`.
+
+{% include vimeo.html id='921273327' %}
+
+## Process recording
+
+In the absence of tests or HTTP requests, AppMap can record an entire
+Node.js application's execution from start to finish. 
+
+Run the `appmap-node` command and give it an argument for starting your application, and it will record the entire
+application's behavior by default.
+
+```
+npx appmap-node <add your Node.js application launch command here>
+```
+{: .example-code}
+
+Then interact with your app using its UI or API, and AppMaps will be generated automatically. 
+
+
+## Viewing AppMaps
+
+Recorded AppMap are saved as `.appmap.json` files `tmp/appmap`. 
+
+Follow the documentation for your IDE to open recorded `.appmap.json` AppMap files:
+- [in VS Code](/docs/reference/vscode)
+- [in JetBrains IDEs](/docs/reference/jetbrains)
+
+## GitHub repository
+
+[https://github.com/getappmap/appmap-node](https://github.com/getappmap/appmap-node)
+
+## Troubleshooting
+
+If you run into any issues, please make sure if you have the latest version by running `npx appmap-node@latest` first.