Note: this agent is currently in early access. It’s meant to replace appmap-agent-js which is no longer in active development. Let us know
if in your project
appmap-node doesn’t work while
appmap-node records AppMaps 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.
Other framework and framework versions not listed here may also work. The AppMap Agent for Node.js should be compatible with any framework that uses the built-in node:http library.
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
node app.js, the following
command would create AppMap recordings of that application’s behavior when it runs:
$ npx appmap-node app.js
appmap-node command works by passing a modified version of the environment variable
to the launch command. This allows it to work with any Node.js command, including ones based on
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
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.
- path: .
Each entry in the
packages list is a YAML object which has the following keys:
- path: dist/users
- path: dist # catch-all to instrument the rest of the code
When running test cases with
appmap-node, a new AppMap file will be created for each unique test case.
Wrap your existing
vitest test command with
appmap-node. For example:
$ npx appmap-node mocha specs/test.js
$ npx appmap-node npm test
When the tests are complete, the AppMaps will be stored in the default output directory
<test-framework> will be one of
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.
appmap-node as normal, passing your application’s starting command as the arguments.
appmap-node will start the app and inject itself in its http stack. It will listen for remote recording requests.
In the absence of tests or HTTP requests, AppMap can record an entire Node.js application’s execution from start to finish.
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>
Then interact with your app using its UI or API, and AppMaps will be generated automatically.
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
Recorded AppMap are saved as
Follow the documentation for your IDE to open recorded
.appmap.json AppMap files: