AppMap Agent for Node.js

Note: This agent replaces appmap-agent-js which is no longer in active development. Let us know if your project is unable to create AppMap Data with appmap-node.

• About
  • Supported versions
• Usage
• Configuration
• Tests recording
  • Recording Mocha, Jest, or Vitest test cases
• Remote recording
• Process recording
• Request recording
• Viewing AppMap Diagrams
• GitHub repository
• Troubleshooting

About

appmap-node records AppMap Data of your Node.js applications.

The AppMap Data Format includes code structure (packages, modules, classes, and methods), trace events (function calls, web services, RPC calls, SQL, parameters, return values, exceptions, etc), and code metadata (repo URL, commit SHA, etc). It’s more granular than a performance profile, but it’s less granular than a full debug trace. It’s designed to be optimal for understanding the design intent and structure of code and key data flows.

Supported versions

AppMap for Node.js can record applications written in both JavaScript and TypeScript.

Usage

npx appmap-node <launch command>

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:

$ npx appmap-node npm run dev

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.

AppMap Data is saved to the directory tmp/appmap by default, and each AppMap file ends in .appmap.json.

NOTE: If you are modifying NODE_OPTIONS as part of the command you use to execute your tests or run your application, ensure you run appmap-node after modifying NODE_OPTIONS. If you run appmap-node and later modify the environment variable you may not have AppMap data created for your project. For more information, refer to this GitHub Issue

For example:

Before

cross-env NODE_PATH=./src NODE_ENV=test NODE_OPTIONS='--max-old-space-size=2048' jest --config .jestrc.json

After

 cross-env NODE_PATH=./src NODE_ENV=test NODE_OPTIONS='--max-old-space-size=2048' appmap-node jest --config .jestrc.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:

name: MyApp
appmap_dir: tmp/appmap
packages:
- path: .
  exclude:
  - node_modules
  - .yarn

• name Provides the project name (auto-detected from package.json).
• appmap_dir Directory to place the AppMap Data 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:

packages:
- path: dist/users
  exclude:
  - util.js
  - findUser
  - UsersController.index
- path: dist # catch-all to instrument the rest of the 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:

$ npx appmap-node mocha specs/test.js
$ npx appmap-node npm test
$ npx appmap-node yarn test

When the tests are complete, the AppMap files will be stored in the default output directory tmp/appmap/<test-framework>, where <test-framework> will be one of mocha, jest, or vitest.

Remote recording

The appmap-node agent supports the AppMap 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.
3. Start the remote recording:
   • in VS Code
   • in JetBrains IDEs
   • with curl
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.

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.

Process recording

In the absence of tests or HTTP requests, AppMap can record an entire Node.js application’s execution from start to finish.

By default, AppMap will create a process recording of your application. This recording will be abandoned (cancelled and the process recording not created) if there are other recordings during the run (such as Request, Remote, or Test recording). Set the APPMAP_RECORDER_PROCESS_ALWAYS environment variable to true and AppMap will continue process recording even if other recordings are encountered.

For example:

APPMAP_RECORDER_PROCESS_ALWAYS=true npx appmap-node <add your Node.js application launch command here>

Otherwise, you can run the appmap-node command with the commands and arguments 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>

Then interact with your app using its UI or API, and AppMap Diagrams will be generated automatically. And when your process finishes or your application exits a process recording will be created in your code editor.

Viewing AppMap Diagrams

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
• in JetBrains IDEs

GitHub repository

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.