Standard Installation


To install the Node agent, you must have installed:

  • A C++ compiler toolchain (e.g., Clang, GCC or MSVC) and a POSIX-compatible make

  • Python (which is needed for Node-gyp, Node's build tool, to function)


  • If you can build other modules with C++ bindings like node-sass and sqlite3, you probably meet all of the requirements for Contrast.
  • The official Node Docker images come with all of the prerequisites installed.


To install the necessary compiler toolchain on Windows, run npm install -g --production windows-build-tools. If you're using a Node version older than 8.0, you must use windows-build-tools version 3.0 (not 4.0, the newest version).


macOS ships with the clang compiler suite. Use clang --version to ensure that you have the compiler installed. If Clang is not already installed, run $ xcode-select --install to install it.


Linux distributions often ship with a C++ compiler toolchain. You can verify that the compiler is installed with c++ --version. If you don't have a C++ compiler installed, install the g++ package available from most Linux package managers.


After downloading from your account, install the agent from your application's root directory as follows:

npm install node-contrast-#.#.#.tgz --no-save

This will add the agent to your node_modules folder without creating an entry in the dependencies list of your package.json.

Note: If you use yarn, you can't run yarn add node-contrast-#.#.#.tgz. Yarn has known issues with packages that contain bundled dependencies like our agent package. Run the following after you install yarn:

 mkdir -p node_modules/node_contrast && tar zxvf node_contrast-#.#.#.tgz --strip 1 -C node_modules/node_contrast


When you download the Node agent, you will also be directed to download a configuration file. By default, the agent looks for this configuration file in your application's root directory and expects the file to be called contrast_security.yaml.

The minimum required contrast_security.yaml setup should look something like this:

  user_name: contrast_user
  api_key: demo
  service_key: demo
Property Description
contrast.api_key Organization's API key
contrast.user_name Contrast user account ID
(In most cases, this is your login ID)
contrast.service_key Contrast user account service key
contrast.url Address of the Contrast installation you would like your agent to report to

For a full list of configuration options that can be placed in this file, see Node Agent Configuration.

Run the Agent

First, add the following script to your application's package.json:

"scripts": {
    "contrast": "node-contrast <app-main>.js",
    "start": ...,
    "test": ...

You can then run the agent with npm run contrast. You can change this npm script to include other runtime configurations, such as an alternate configuration file location. For more information, see Node Agent Configuration.

Installation on Bluemix

Use the Contrast agent to instrument Node applications deployed on IBM Bluemix. The following steps walk you through the installation process.


  • Download the Node.js agent from Contrast.

  • Download the contrast_security.yaml file from Contrast.


  • In the contrast_security.yaml file, you can configure the name of the server to which this application will report. (Contrast recommends that you complete this step to avoid creating duplicate servers in the application.) To configure the server name as "BluemixNodeServer" in Contrast, add BluemixNodeServer.


   user_name: contrast_user
   api_key: demo
   service_key: demo
   name: BluemixNodeServer

Note: To find other options for customizing the Node agent, go to the Configuration article.

  • Create a folder named contrast in your application’s root directory.

  • Move the node-contrast-.tgz and the contrast_security.yaml files into the contrast folder.

  • In the application’s package.json file, create a new script. For a startup script named index.js, add the following line:

"bluemix-with-contrast": "npm install /home/vcap/app/contrast/node-contrast-
x.y.z.tgz && node-contrast index.js -c /home/vcap/app/contrast/contrast_security.yaml",

Run the Agent

  • Since Bluemix runs the start script by default, you must change the start command to point to the bluemix-with-contrast line given in the previous step.
"start":"npm run bluemix-with-contrast"
Now the scripts section of the package.json should look like the following:
"scripts": {
"bluemix-with-contrast": "npm install /home/vcap/app/contrast/node-contrast-
x.y.z.tgz && node-contrast index.js -c /home/vcap/app/contrast/contrast_security.yaml",
"start":"npm run bluemix-with-contrast”
  • Push the application to Bluemix using cf push <application name> -t 180.

Once the the deploy is finished, you should see the application in Contrast.