Before you begin
If at any point you would like some help getting installed please open a support ticket by sending an email to support@appmap.io and we will schedule some time to get you set up.
Before you can make AppMaps, you’ll need to install the AppMap “agent” for your programming language. The AppMap “agent” is a library (Ruby gem, Python / JavaScript / Java package) that you install using your dependency manager (Rubygems, Pip, Npm, Yarn, Maven, Gradle, etc).
For JavaScript and Java, you’ll also need to create a file called appmap.yml and provide some configuration settings. (Creation of this file is optional for Ruby and Python, however).
You can install the AppMap agent manually, using the documented instructions. Or, you can run the command-line
installation and configuration utility
npx @appland/appmap@latest install
. As you can see, the installer requires Node.js - so if you don’t have Node installed and
you don’t want to install it, you can use the manual install procedure.
Open a terminal window in the top level folder of your project and run this command:
npx @appland/appmap@latest install
You will be guided through a series of steps for installing and configuring that agent, that will look something like this:
$ npx @appland/appmap@latest install
Need to install the following packages:
@appland/appmap@3.50.1
Ok to proceed? (y)
✔ Installing AppMap...
? Commit these files to your repo so that everyone on your team can use AppMap
without them having to repeat the setup process. Bring runtime code analysis
to your whole team!
Gemfile
Gemfile.lock
appmap.yml
Commit? Yes
✔ Validating the AppMap agent...
╭─────────────────────────────────────────────────────────────────────╮
│ │
│ Success! AppMap has finished installing. │
│ │
│ NEXT STEP: Record AppMaps │
│ │
│ You can consult the AppMap documentation, or continue with the │
│ instructions provided in the AppMap code editor extension. │
│ │
╰─────────────────────────────────────────────────────────────────────╯
The installer changes your project’s build process (yarn.lock for Javascript, Gemfile for Ruby, etc) to run AppMap when the tests run and when developing locally. It doesn’t affect production.
AppMap recommends you commit to Git the files changed by the AppMap installer so that everyone on your team can use AppMap without them having to repeat the setup process. This brings runtime code analysis to your whole team!
After you have installed the agent and commited AppMap to Git, proceed to Record AppMaps.
Node.js (usually referred to simply as “Node”) is a widely-used open source implementation of JavaScript for desktop and server environments.
The AppMap agent installer relies on a tool called npx
to run our interactive CLI installer. npx
is included in all modern Node.js installations, so installing Node.js will also install npx automatically.
You can check to see if you have Node.js installed (and which version is present, if any) by running this in your terminal:
node -v
If this command prints a version like v16.15.0
or similar, and the version is newer than v14
, you very likely have the right version of Node.js installed,continue your AppMap Agent installation.
If you do not have Node.js installed, or if you have a version that is older than version v14
then you should first install nvm, the Node.js Version Manager.
We recommend that you use Node.js Version Manager (nvm) to install Node.js on your machine. Nvm makes managing and installing different versions of Node.js very simple.
First, check to see if nvm is already installed on your system using this command:
nvm -v
If you do not have nvm installed, follow the instructions for installing nvm (Mac/Linux) or nvm-windows (Windows).
Once you have nvm installed, use this commands to install and use the latest ‘long term support’ version of Node.js:
nvm install --lts
Now that you have Node.js installed you will also now have npx
installed. You can continue with your AppMap agent installation.