AppMap Agent for JavaScript

About

appmap-agent-js is a JavaScript agent for recording AppMaps of your code. “AppMap” is a data format which records code structure (modules, classes, and methods), code execution events (function calls and returns), and code metadata (repo name, repo URL, commit SHA, labels, 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.

There are several ways to record AppMaps of your JavaScript program using the appmap agent:

  • Run your tests (mocha) with the JavaScript agent. An AppMap will be generated for each test.
  • Run your application server with AppMap remote recording enabled, and use the AppMap browser extension to start, stop, and upload recordings.

Once you have made a recording, there are two ways to view automatically generated diagrams of the AppMaps.

The first option is to load the diagrams directly in your IDE, using the AppMap for WebStorm or other JetBrains IDE or AppMap for Visual Studio Code.

The second option is to upload them to app.land using the AppMap CLI.

Supported versions

Installation

Run this command in your Node.js project folder (where package.json is located):

npx @appland/appmap install

You will be guided through a series of steps for installing and configuring the agent.

To use remote recording, and view and interact with recorded AppMaps, we recommend installing the AppMap extension for popular code editors:

Configuration

When you run your program, the agent reads configuration settings from appmap.yml. The install command creates a default appmap.yml file by scanning the project directories. We recommend that you review the generated appmap.yml file and confirm your application name and a list of directories that will be recorded.

Here’s a sample configuration file for a typical JavaScript project:

# 'name' should generally be the same as the code repo name.
name: MyApp
packages:
  - path: src/server/controllers
  - path: src/server/data
  - path: src/server/models
  - path: src/server/routes
  - path: src/server/lib
    shallow: true
    exclude: 
      - src/server/lib/util
  • name Provides the project name (required)
  • packages A list of packages, classes and methods 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 sources files
    • For projects with JavaScript source maps: add paths to sources to be recorded. For example: ```yaml name: MyApp packages:
      • path: src/server/controllers
      • path: src/server/routes ```
    • For projects without JavaScript source maps: include build folders. For example: ```yaml name: MyApp packages:
      • path: dist/controllers
      • path: dist/routes ```
  • exclude A list of 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.

Recording AppMaps from test cases

When running test cases with the agent attached to the JavaScript engine, a new AppMap file will be created for each unique test case.

Recording mocha test cases:

  1. Run appmap-agent-js with the mocha command and its parameters following the -- delimiter. For example: 
     npx appmap-agent-js -- mocha test/**/*.ts
  2. appmap-agent-js will run the tests. When the tests are complete, the AppMaps will be stored in the default output directory tmp/appmap/mocha.

Remote recording

appmap-agent-js supports the AppMap remote recording API. This functionality is provided by the AppMap agent. It will hook an existing HTTP engine, serving HTTP requests to toggle recording on and off.

  1. Run appmap-agent-js with the application-starting command and its parameters following the -- delimiter. For example: 
     npx appmap-agent-js -- node app/main.js --param1 hello --param2=world
  2. appmap-agent-js will start the app and inject itself in its http stack. It will listen for remote recording requests on all http ports of the application.
  3. Start the remote recording:
  4. Interact with your application or service to exercise code included in appmap.yml
  5. Stop the recording and save the new AppMap to disk.

appmap-agent-js parameters

The most frequently used appmap-agent-js parameters are:

  • --recorder=[mocha|remote|process] : process recorder
    • default recorder is inferred from the starting command:
      • mocha if the the command contains mocha
      • remote in all other cases
    • mocha recorder records AppMaps from test cases automatically
    • remote recorder has to be started and stopped manually with http requests
    • process recorder records entire processes automatically, from start to finish
      • Warning: AppMaps recorded with the process recorder can be excessively large and noisy.
  • --command="_start command_" : alternate method of specifying the app- or tests-starting command, wrapped in quotes
  • --log-level=[debug|info|warning|error] : defaults to info
  • --log-file=_file_ : defaults to stderr
  • --output-dir=_directory_ : location of recorded AppMap files, default is tmp/appmap or tmp/appmap/mocha
  • --help prints out help message to stdout
  • --version installed version

Example

npx appmap-agent-js --recorder=mocha --command="mocha test/**/*.ts" --log-level=error

System Properties

  • APPMAP_CONFIGURATION_PATH Path to the appmap.yml config file. Default: appmap.yml
  • APPMAP_REPOSITORY_DIRECTORY Path to the project’s local git folder. Default: .

Viewing AppMaps

Recorded AppMap are saved as .appmap.json files in the project folders (default location: tmp/appmap.)

Follow the documentation for your IDE to open the recorded .appmap.json files:

GitHub repository

https://github.com/applandinc/appmap-agent-js

Was this page helpful? thumb_up Yes thumb_down No
Thank you for your feedback!