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.
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
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.
# '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
Each entry in the
packages list is a YAML object which has the following keys:
pathspecified 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:
mochacommand and its parameters following the
--delimiter. For example:
npx appmap-agent-js -- mocha test/**/*.ts
appmap-agent-jswill run the tests. When the tests are complete, the AppMaps will be stored in the default output directory
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-jswith 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-jswill start the app and inject itself in its http stack. It will listen for remote recording requests on all http ports of the application.
The most frequently used
appmap-agent-js parameters are:
--recorder=[mocha|remote|process]: process recorder
mochaif the the command contains
remotein all other cases
mocharecorder records AppMaps from test cases automatically
remoterecorder has to be started and stopped manually with http requests
processrecorder records entire processes automatically, from start to finish
processrecorder 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
--log-file=_file_: defaults to
--output-dir=_directory_: location of recorded AppMap files, default is
--helpprints out help message to stdout
npx appmap-agent-js --recorder=mocha --command="mocha test/**/*.ts" --log-level=error
APPMAP_CONFIGURATION_PATHPath to the
appmap.ymlconfig file. Default: appmap.yml
APPMAP_REPOSITORY_DIRECTORYPath to the project’s local git folder. Default: .
Recorded AppMap are saved as
.appmap.json files in the project folders (default location:
Follow the documentation for your IDE to open the recorded