How to run the Node Agent with Process Monitoring Tools

Objective

Most process monitoring tools start your application themselves so they can keep track of the process as necessary. Contrast starts your application as part of its own process. As such, there are no known compatibility issues between process management tools and Contrast. However, it may take a bit of configuration to get things working as expected.

We recommend creating a new configuration for your tool, rather than modifying an existing one. The important necessary change should be in the 'script' you have your tool configured to run. The tool needs to pass the agent as an argument to the NodeJS binary. Wherever arguments to the script can be set, the entry point to the application should be specified.

To illustrate the purpose of the change, take the example of running an application normally, where the application entry point is an argument to the NodeJS binary:

node app.js

Compare it to what the npm run contrast command does, where the agent is passed as an argument to the NodeJS binary: 

node --import @contrast/agent app.js

The process monitoring tool needs to be configured such that Contrast is an argument to the NodeJS interpreter, as it is above. 

Process

Using PM2 as an example, here are two recommended methods for running this process monitoring tool with Contrast:

Command Line

The command used to run Contrast normally can be passed into pm2 via a command line argument:

pm2 start --name appName_contrast --node-args="--import @contrast/agent"

Note that the --name flag is optional here.

Creating A New Configuration

When creating a new configuration, the two important attributes needed for running with Contrast are node_args and script. A sample configuration may look like this:

{
  apps : [

    // First application
    {
      name      : "API",
      script    : "app.js",
      env: {
        COMMON_VARIABLE: "true"
      },
      env_production : {
        NODE_ENV: "production"
      }
    },
    // First application with Contrast; note different production environment
    {
      name      : "API - Contrast",
      node_args : ["--import", "@contrast/agent"]
      script    : "app.js",
      env: {
        COMMON_VARIABLE: "true"
      },
      env_production : {
        NODE_ENV: "development"
      }
    },
  ], {
      ...
  }
}

{
  apps: [
    {
      name: "API - Contrast",
      node_args: ['--import', '/api/node_modules/@contrast/agent'], // Full path to the Contrast agent is required
      script: "app.js",
      instances: "2",
      exec_mode: "cluster",
      env: {
        NODE_ENV: "development"
      }
    }
  ]
}