appmap-agent-js
is a JavaScript package for recording AppMaps of your code.
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.
AppMap for JavaScript is currently in early access. Requirements:
Supported frameworks:
Other frameworks not listed here may also work. The AppMap Agent for JavaScript should be compatible with any framework that uses the built-in node:http library.
Run this command in your Node.js project folder (where package.json
is located):
npx @appland/appmap@latest 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:
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
packages
Each entry in the packages
list is a YAML object which has the following keys:
path
specified in the same package entry.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
.When running test cases with the agent attached to the JavaScript engine, a new AppMap file will be created for each unique test case.
appmap-agent-js
with the mocha
command and its parameters following the --
delimiter.
For example:
npx appmap-agent-js -- mocha 'test/**/*.ts'
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
.appmap-agent-js
with the jest
command and its parameters following the --
delimiter.
For example:
npx appmap-agent-js -- jest 'test/**/*.ts'
appmap-agent-js
will run the tests. When the tests are complete, the AppMaps will be stored
in the default output directory tmp/appmap/jest
.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.
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
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.appmap.yml
appmap-agent-js
parametersThe most frequently used appmap-agent-js
parameters are:
--recorder=[mocha|jest|remote|process]
: process recorder
mocha
if the the command contains mocha
jest
if the the command contains jest
process
in all other casesmocha
and jest
recorders record AppMaps from test cases automaticallyremote
recorder has to be started and stopped manually with http requestsprocess
recorder records entire processes automatically, from start to finish
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/<recorder>
– eg: tmp/appmap/mocha
--help
prints out help message to stdout--version
installed versionnpx appmap-agent-js --log-level=error --recorder=remote --command="node built/app.js"
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: .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:
https://github.com/getappmap/appmap-agent-js